在文件 URL 中嵌入值

透過將特定參數與變數值直接嵌入共享文件 URL 中，提升協作效率。預設情況下，共享文件僅包含 API 規格。此功能可讓你分享預先填入的值，讓使用者更容易使用特定設定來測試端點。

參數行為

透過 URL 傳遞的參數值會根據其類型而有不同的行為：

環境變數：透過 URL 設定的值會全域套用至文件中的所有端點。它們會在端點之間導覽或開啟新分頁時持續保留，直到被明確覆寫或手動變更為止

請求參數（Query、Path、Body、Header、Cookie）：這些值的範圍僅限於透過 URL 存取的特定端點，並且不會在導覽至其他端點時保留

傳遞參數值

有兩種方法可用於嵌入參數值：簡易模式與複雜模式。簡易模式更精簡，且不需要 URL 編碼，但無法處理方括號字元。複雜模式支援所有字元，但需要對參數資料進行 URL 編碼。

簡易模式

簡易模式使用 parameterType[parameterName]=value 格式。

範例：

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?environment[access_token]=example_value&query[locale]=en-US

參數類型	參數值格式	說明	行為
Query 參數	`query[xxx]=yyy`		僅限目前端點
Path 參數	`path[xxx]=yyy`		僅限目前端點
Body 參數	`body[xxx]=yyy`	適用於 `form-data` 或 `x-www-form-urlencoded` 主體類型	僅限目前端點
Body 參數	`body=yyy`	適用於其他主體類型（例如 raw JSON、XML）	僅限目前端點
Header 參數	`header[xxx]=yyy`		僅限目前端點
Cookie 參數	`cookie[xxx]=yyy`		僅限目前端點
環境變數	`environment[xxx]=yyy`	在預設環境中設定值。	跨端點保留

複雜模式

複雜模式會將 URL 編碼後的 JSON 物件作為 params 參數的值傳遞。此 JSON 物件必須使用 encodeURIComponent 進行編碼。在 JavaScript 中，可透過以下方式達成：encodeURIComponent(JSON.stringify({"query":["id",1]}))。

範例 JSON（編碼前）：

{
    "query": [
        ["id", "value1"],
        ["id", "value2"],
        ["key2", "value3"]
    ],
    "path": [
        ["key1", "value1"],
        ["key2", "value2"]
    ],
    "body": [
        ["aaa", "value1"],
        ["key2", "value2"]
    ],
    "header": [
        ["testHeader", "value1"],
        ["key2", "value2"]
    ],
    "cookie": [
        ["testCookie", "value1"],
        ["key2", "value2"]
    ],
    "environment": [
        ["access_token", "example_value"],
        ["projectId", "1"]
    ]
}

範例 URL（編碼後）：

https://apidog.com/apidoc/docs-site/538323/api-7312738-run?params=%7B%22query%22%3A%5B%5B%22id%22%2C%22value1%22%5D%2C%5B%22id%22%2C%22value2%22%5D%2C%5B%22key2%22%2C%22value3%22%5D%5D%2C%22path%22%3A%5B%5B%22key1%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22body%22%3A%5B%5B%22aaa%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22header%22%3A%5B%5B%22testHeader%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22cookie%22%3A%5B%5B%22testCookie%22%2C%22value1%22%5D%2C%5B%22key2%22%2C%22value2%22%5D%5D%2C%22environment%22%3A%5B%5B%22access_token%22%2C%22example_value%22%5D%2C%5B%22projectId%22%2C%221%22%5D%5D%7D

參數類型	參數值	說明	行為
Query 參數	`query`	鍵值對陣列。	僅限目前端點
Path 參數	`path`	鍵值對陣列。	僅限目前端點
Body 參數	`body`	適用於 `form-data` 或 `x-www-form-urlencoded` 的鍵值對陣列；其他主體類型則為字串。	僅限目前端點
Header 參數	`header`	鍵值對陣列。	僅限目前端點
Cookie 參數	`cookie`	鍵值對陣列。	僅限目前端點
環境變數	`environment`	鍵值對陣列。在預設環境中設定值。	跨端點保留

傳遞環境變數

若要為使用者自動設定環境變數，請將它們包含在 URL 中。這些變數會在文件中的所有端點之間持續保留。

範例：

https://openapi.apidog.io/api-7312738-run?environment[access_token]=example_value

最佳實務

環境變數會跨端點保留，而其他參數類型（query、path、body、header、cookie）的範圍則限定於 URL 中的特定端點。此方法最適合用於在多個端點之間分享可重複使用的值。

在文件 URL 中嵌入值

參數行為#

傳遞參數值#

簡易模式#

複雜模式#

傳遞環境變數#

參數行為

傳遞參數值

簡易模式

複雜模式

傳遞環境變數