Azure REST API 參考

發行項
04/04/2024

歡迎使用 Azure REST API 參考檔。

具象狀態傳輸 (REST) API 是支援一組 HTTP 作業 (方法) 的服務端點，提供服務資源的建立、擷取、更新或刪除存取權限。本文將引導您：

如何使用 curl 呼叫 Azure REST API
REST API 要求/回應組的基本元件。
如何使用 Microsoft Entra ID 註冊用戶端應用程式，以保護 REST 要求。
建立和傳送 REST 要求的概觀，以及處理回應。

提示

大部分的 Azure 服務 REST API 都有用戶端連結庫，可提供使用 Azure 服務的原生介面：

。網 | Java | | Node.jsPython | 去 | C++

如何使用 curl 呼叫 Azure REST API

下列部落格文章中所述的程序示範如何使用 curl 呼叫 Azure REST API。您可能會考慮在自動腳本中使用 curl。例如，在DevOps自動化案例中。

透過 curl 呼叫 Azure REST API

REST API 要求/回應的元件

REST API 要求/回應配對可分成五個元件：

由 {URI-scheme} :// {URI-host} / {resource-path} ? {query-string} 所組成的要求 URI。雖然要求 URI 包含在要求訊息標頭中，但由於大多數語言或架構要求您將它與要求訊息分開傳遞，因此我們會另外呼叫它。
- URI 配置：表示用來傳輸要求的通訊協定。例如，http 或 https。
- URI 主機：指定裝載 REST 服務端點之伺服器的網域名稱或 IP 位址，例如 graph.microsoft.com。
- 資源路徑：指定資源或資源集合，其中可能包含服務用來判斷這些資源選取的多個區段。例如：beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 可用來查詢應用程式集合中特定應用程式的擁有者清單。
- 查詢字串 (選用)：提供其他簡單參數，例如 API 版本或資源選取準則。
HTTP 要求訊息標頭 欄位：
- 必要的 HTTP 方法 (也稱為作業或動詞) ，告知服務您要求的作業類型。 Azure REST API 支援 GET、HEAD、PUT、POST 和 PATCH 方法。
- 指定的 URI 和 HTTP 方法所需的其他選擇性標頭欄位。例如，提供持有人令牌的授權標頭，其中包含要求的用戶端授權資訊。
選擇性的 HTTP 要求訊息主體欄位，以支援 URI 和 HTTP 作業。例如，POST 作業包含當作複雜參數傳遞的 MIME 編碼物件。針對 POST 或 PUT 作業，也必須在 Content-type 要求標頭中指定主體的 MIME 編碼類型。某些服務要求您使用特定 MIME 類型，例如 application/json。
HTTP 回應訊息標頭欄位：
- HTTP 狀態碼，範圍可介於 2xx 成功碼到 4xx 或 5xx 錯誤碼之間。或者，可能會傳回服務定義的狀態碼，如 API 文件中所示。
- 支援要求回應所需的其他選擇性標頭欄位，例如 Content-type 回應標頭。
選擇性的 HTTP 回應訊息主體欄位：
- MIME 編碼回應物件會在 HTTP 回應主體中傳回，例如來自傳回資料之 GET 方法的回應。一般而言，這些物件會以 JSON 或 XML 等結構化格式傳回，如 Content-type 回應標頭所示。例如，當您從 Microsoft Entra ID 要求存取令牌時，它會在回應本文中當做 access_token 元素傳回，這是數據收集中數個名稱/值配對物件的其中一個。在此範例中，也會包含的 Content-Type: application/json 響應標頭。

向 Microsoft Entra ID 註冊客戶端應用程式

大部分的 Azure 服務 (例如 Azure Resource Manager 提供者和傳統部署模型) 要求用戶端程式代碼使用有效的認證進行驗證，才能呼叫服務的 API。驗證會透過 Microsoft Entra ID 在各種動作專案之間進行協調，並提供您的用戶端存取令牌作為驗證證明。令牌接著會在後續 REST API 要求的 HTTP 授權標頭中傳送至 Azure 服務。令牌的宣告也會提供資訊給服務，讓它能夠驗證客戶端並執行任何必要的授權。

如果您使用未使用整合式 Microsoft Entra 驗證的 REST API，或已經註冊用戶端，請跳至 [建立要求] 區段。

必要條件

用戶端應用程式必須在 Microsoft Entra 租用戶中註冊它，讓其身分識別設定在運行時間之前先 Microsoft Entra ID。使用 Microsoft Entra ID 註冊用戶端之前，請考慮下列必要條件：

如果您還沒有 Microsoft Entra 租使用者，請參閱設定 Microsoft Entra 租使用者。
根據 OAuth2 授權架構，Microsoft Entra ID 支援兩種類型的用戶端。瞭解每個項目可協助您決定最適合您的案例：
- Web/機密用戶端會在網頁伺服器上執行，而且可以在自己的身分識別下存取資源 (，例如服務或精靈) ，或取得委派的授權，以存取登入使用者身分識別下的資源 (，例如 Web 應用程式) 。只有 Web 用戶端可以在 Microsoft Entra 驗證期間安全地維護並呈現自己的認證，以取得存取令牌。
- 原生/公用用戶端會在裝置上安裝並執行。他們只能在委派授權下存取資源，使用登入使用者的身分識別來代表使用者取得存取令牌。
註冊程式會在註冊應用程式的 Microsoft Entra 租使用者中建立兩個相關物件：應用程式對象和服務主體物件。如需這些元件及其在運行時間使用方式的詳細資訊，請參閱 Microsoft Entra ID 中的應用程式和服務主體物件。

您現在已準備好向 Microsoft Entra ID 註冊用戶端應用程式。

用戶端註冊

若要註冊存取 Azure Resource Manager REST API 的用戶端，請參閱使用入口網站建立可存取資源的 Microsoft Entra 應用程式和服務主體。 PowerShell 和 CLI 版本也提供 (，以自動化註冊) 說明如何：

使用 Microsoft Entra ID 註冊客戶端應用程式。
設定許可權要求以允許用戶端存取 Azure Resource Manager API。
設定 Azure Resource Manager Role-Based 存取控制 (RBAC) 設定來授權用戶端。

如果您的用戶端存取 Azure Resource Manager API 以外的 API，請參閱：

使用 Microsoft 身分識別平台來註冊應用程式
- 在 [註冊應用程式] 區段中，向 Microsoft Entra ID 註冊客戶端應用程式。
- 如果您要在 [新增認證] 區段中註冊 Web 用戶端) ，請 (建立秘密密鑰。
設定應用程式以公開 Web API
- 將許可權新增至 Web API，並將其公開為範圍
設定用戶端應用程式以存取 Web API
- 在 [新增存取 Web API 的許可權] 區段中，新增 API 定義範圍所需的許可權要求。

既然您已完成用戶端應用程式的註冊，請移至用戶端程序代碼，在其中建立 REST 要求並處理回應。

建立要求

本節涵蓋我們稍早討論的五個元件的前三個部分。您必須先從 Microsoft Entra ID 取得存取令牌，以用來組合要求訊息標頭。

取得存取權杖

擁有有效的客戶端註冊之後，您有兩種方式可以與 Microsoft Entra ID 整合，以取得存取令牌：

本文中使用的平臺和語言中性 OAuth2 服務端點。本節中提供的指示假設您在使用 Microsoft Entra OAuth 端點時，不會假設客戶端的平台或語言/腳本。唯一的需求是您可以在 Microsoft Entra ID 傳送/接收 HTTPS 要求，並剖析回應訊息。
平台和語言特定的 Microsoft 驗證連結庫 (MSAL) ，超出本文的範圍。連結庫會提供 OAuth2 端點要求的異步包裝函式，以及健全的令牌處理功能，例如快取和重新整理令牌管理。如需詳細資訊，請參閱 MSAL) (Microsoft 驗證連結庫概觀。

您用來驗證用戶端並取得存取令牌的兩個 Microsoft Entra 端點稱為 OAuth2 /authorize 和/token端點。使用方式取決於您應用程式的註冊，以及運行時間支援應用程式所需的 OAuth2 授權授與流程類型。為了本文的目的，我們假設您的用戶端使用下列其中一個授權授與流程：授權碼或客戶端認證。若要取得其餘各節中使用的存取令牌，請遵循最符合您案例之流程的指示。

授權碼授與互動式用戶端 ()

Web 和原生用戶端都會使用此授與，需要來自已登入用戶的認證，才能將資源存取委派給用戶端應用程式。它會使用 /authorize 端點來取得授權碼 (，以回應使用者登入/同意) ，後面接著 /token 端點來交換存取令牌的授權碼。

首先，您的客戶端必須向 Microsoft Entra ID 要求授權碼。如需端點 HTTPS GET 要求 /authorize 格式的詳細資訊，以及範例要求/回應訊息，請參閱要求授權碼。 URI 包含下列查詢字串參數，這些參數是用戶端應用程式特有的：
- client_id：在註冊期間指派給用戶端應用程式的 GUID，也稱為應用程式識別碼。
- redirect_uri：在用戶端應用程式註冊期間指定的其中一個回復/重新導向 URI URL 編碼版本。您傳遞的值必須完全符合您的註冊值。
- resource：您呼叫的 REST API 所指定的 URL 編碼識別碼 URI。 Web/REST API (也稱為資源應用程式，) 可以在其設定中公開一或多個應用程式標識碼 URI。例如：
  - Azure Resource Manager 提供者 (和傳統部署模型) API 使用 https://management.core.windows.net/。
  - 如需任何其他資源，請參閱 #DE91BD84918BA4A98BE6021B298A8250D 中的 API 檔或資源應用程式的組態。如需詳細資訊，請參閱 identifierUris Microsoft 圖形 API 應用程式對象的屬性。
對端點的要求 /authorize 會先觸發登入提示，以驗證使用者。您傳回的回應會以重新導向 (302) 傳遞至您在中指定的 redirect_uriURI。響應標頭訊息包含 location 欄位，其中包含重新導向 URI，後面接著 code 查詢參數。參數 code 包含步驟 2 所需的授權碼。
接下來，您的客戶端必須兌換存取令牌的授權碼。如需端點的 HTTPS POST 要求 /token 格式和要求/回應範例的詳細資訊，請參閱要求存取令牌。因為這是 POST 要求，所以您會在要求本文中封裝您的應用程式特定參數。除了一些先前提及的參數 (，以及其他) 的新參數之外，您還會傳遞：
- code：此查詢參數包含您在步驟 1 中取得的授權碼。
- client_secret：只有當用戶端設定為 Web 應用程式時，才需要此參數。這是您稍早在用戶端註冊中產生的相同秘密/金鑰值。

用戶端認證會授與 (非互動式用戶端)

此授與只會由 Web 用戶端使用，允許應用程式直接存取資源， (不會使用在註冊時提供的客戶端認證，) 存取任何使用者委派。授與通常是由非互動式用戶端使用， (執行為服務或精靈的 UI) 。它只需要 /token 端點才能取得存取令牌。

此授與的用戶端/資源互動類似於授權碼授與的步驟 2。如需端點的 HTTPS POST 要求/token格式和要求/回應範例的詳細資訊，請參閱 Microsoft 身分識別平台和 OAuth 2.0 用戶端認證流程中的一節。

組合要求訊息

大部分的程式設計語言或架構和腳本環境可讓您輕鬆地組合並傳送要求訊息。它們通常會提供 Web/HTTP 類別或 API，以抽象化建立或格式化要求，讓您更輕鬆地在 .NET Framework 中撰寫用戶端程式代碼 HttpWebRequest (類別，例如) 。為了簡潔起見，因為大部分的工作都會為您處理，本節只涵蓋要求的重要元素。

要求 URI

因為正在傳輸和接收敏感性資訊，所以所有 REST 要求都需要 HTTPS 通訊協定以進行 URI 配置，並提供要求和回應安全通道。資訊 (，也就是 Microsoft Entra 授權碼、存取/持有人令牌，以及敏感性要求/回應數據) 會由較低的傳輸層加密，以確保訊息的隱私權。

您服務的其餘要求 URI (主機、資源路徑，以及任何必要的查詢字串參數) 取決於其相關的 REST API 規格。例如，Azure Resource Manager 提供者 API 使用 https://management.azure.com/，而 Azure 傳統部署模型會使用 https://management.core.windows.net/。兩者 api-version 都需要查詢字串參數。

要求標頭

要求 URI 隨附於要求訊息標頭中，以及服務 REST API 規格和 HTTP 規格所需的任何其他字段。您的要求可能需要下列通用標頭欄位：

Authorization：包含OAuth2 持有人令牌來保護要求的安全，如先前從 Microsoft Entra ID 取得。
Content-Type：通常設定為 “application/json” (JSON 格式的名稱/值組) ，並指定要求本文的 MIME 類型。
Host：裝載 REST 服務端點之伺服器的功能變數名稱或 IP 位址。

要求本文

如先前所述，要求訊息本文是選擇性的，視您要求的特定作業及其參數需求而定。如果需要，您要求之服務的 API 規格也會指定編碼和格式。

要求本文會以空行分隔，根據標頭字段格式化 Content-Type 。 “application/json” 格式化本文的范例如下所示：

{
  "<name>": "<value>"
}

傳送要求

既然您已擁有服務的要求 URI，並已建立相關的要求訊息標頭和本文，您就可以將要求傳送至 REST 服務端點。

例如，您可以使用類似下列 (的要求標頭字段，為 Azure Resource Manager 提供者傳送 HTTPS GET 要求方法，請注意要求本文是空的) ：

GET /subscriptions?api-version=2014-04-01-preview HTTP/1.1
Authorization: Bearer <bearer-token>
Host: management.azure.com

<no body>

您也可以使用類似下列範例的要求標頭和文字段，為 Azure Resource Manager 提供者傳送 HTTPS PUT 要求方法：

PUT /subscriptions/.../resourcegroups/ExampleResourceGroup?api-version=2016-02-01  HTTP/1.1
Authorization: Bearer <bearer-token>
Content-Length: 29
Content-Type: application/json
Host: management.azure.com

{
  "location": "West US"
}

提出要求之後，會傳回回應消息標頭和選擇性本文。

處理回應消息

此程式會以五個元件的最後兩個元件結束。

若要處理回應，請剖析回應標頭，並視要求) ，選擇性地剖析回應本文 (。在上一節提供的 HTTPS GET 範例中，您已使用 /subscriptions 端點來擷取使用者的訂用帳戶清單。假設回應成功，您應該會收到類似下列範例的響應標頭字段：

HTTP/1.1 200 OK
Content-Length: 303
Content-Type: application/json;

您應該會收到回應本文，其中包含以 JSON 格式編碼的 Azure 訂用帳戶清單及其個別屬性，如下所示：

{
    "value":[
        {
        "id":"/subscriptions/...",
        "subscriptionId":"...",
        "displayName":"My Azure Subscription",
        "state":"Enabled",

"subscriptionPolicies":{
            "locationPlacementId":"Public_2015-09-01",
            "quotaId":"MSDN_2014-05-01",
            "spendingLimit":"On"}
        }
    ]
}

同樣地，針對 HTTPS PUT 範例，您應該會收到類似下列的響應標頭，確認要新增 “ExampleResourceGroup” 的 PUT 作業成功：

HTTP/1.1 200 OK
Content-Length: 193
Content-Type: application/json;

您應該會收到回應本文，確認以 JSON 格式編碼之新新增的資源群組內容，如下所示：

{
    "id":"/subscriptions/.../resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

如同要求，大部分的程式設計語言和架構都可讓您輕鬆地處理回應訊息。它們通常會在要求之後將此資訊傳回至您的應用程式，讓您以具型別/結構化格式處理它。主要是，您有興趣確認回應標頭中的 HTTP 狀態代碼，並根據 API 規格 (或 Content-Type 和 Content-Length 回應標頭字段) 剖析回應本文。

異步操作、節流和分頁

本文所討論的建立/傳送/處理回應模式是同步的，並適用於所有 REST 訊息。不過，某些服務也支援異步模式，這需要額外的響應標頭處理，才能監視或完成異步要求。如需詳細資訊，請參閱追蹤非同步 Azure 作業。

Resource Manager 每小時套用讀取和寫入要求數目的限制，以防止應用程式傳送太多要求。如果您的應用程式超過這些限制，則會對要求進行節流。響應標頭包含您範圍的剩餘要求數目。如需詳細資訊，請參閱對 Resource Manager 要求進行節流(機器翻譯\)。

某些清單作業會傳回回應本文中稱為 nextLink 的屬性。當結果太大而無法以一個回應傳回時，您會看到這個屬性。一般而言，當列表作業傳回超過1,000個專案時，回應會包含 nextLink 屬性。當結果中沒有 nextLink 時，傳回的結果就會完成。當 nextLink 包含 URL 時，傳回的結果只是總結果集的一部分。

回應的格式如下：

{
  "value": [
    <returned-items>
  ],
  "nextLink": "https://management.azure.com/{operation}?api-version={version}&%24skiptoken={token}"
}

若要取得結果的下一頁，請將 GET 要求傳送至 nextLink 屬性中的 URL。 URL 包含接續令牌，以指出您在結果中的位置。繼續將要求傳送至 nextLink URL，直到它不再包含傳回結果中的 URL 為止。

Azure API 的復原

Azure REST API 是專為復原和持續可用性而設計。控制平面作業 (傳送至 REST API 中 management.azure.com) 的要求如下：

會跨區域分散。有些服務是區域性的。
會在有多個可用性區域的位置中跨可用性區域 (以及區域) 分散。
不依賴單一邏輯資料中心。
永遠不會停機進行維護活動。

就這麼簡單。當您註冊 Microsoft Entra 應用程式，並具有取得存取令牌和處理 HTTP 要求的模組化技術之後，複寫程式代碼就能利用新的 REST API 相當容易。如需應用程式註冊和 Microsoft Entra 程式設計模型的詳細資訊，請參閱 Microsoft 身分識別平台檔。

如需測試 HTTP 要求/回應的相關信息，請參閱：

Fiddler。 Fiddler 是可攔截 REST 要求的免費 Web 偵錯 Proxy，讓您輕鬆就能診斷 HTTP 要求/回應訊息。
JWT.ms，可讓您在持有人令牌中快速輕鬆地傾印宣告，以便驗證其內容。