Azure REST API 參考

發行項
08/05/2023

歡迎使用 Azure REST API 參考。

表示狀態傳輸 (REST) API 是支援一組 HTTP 作業的服務端點， (方法) ，可提供服務的資源的建立/擷取/更新/刪除存取。下列各節將逐步引導您完成：

REST API 要求/回應組的基本元件
如何使用 Azure Active Directory (Azure AD 註冊用戶端應用程式) 來保護 REST 要求
建立和傳送 REST 要求的概觀，以及處理回應

注意

大部分的 Azure 服務 REST API 都有對應的用戶端 SDK 程式庫，可為您處理大部分的用戶端程式代碼。請參閱：

Azure .NET SDK
Azure Java SDK
Azure CLI 2.0 SDK

REST API 要求/回應的元件

REST API 要求/回應組可以分成 5 個元件：

由 {URI-scheme} :// {URI-host} / {resource-path} ? {query-string} 所組成的要求 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 編碼物件。本文的 MIME 編碼類型也應該在要求標頭中 Content-type 指定，以用於 POST/PUT 作業。請注意，某些服務會要求您使用特定的 MIME 類型，例如 application/json 。
HTTP 回應訊息標頭 欄位
- HTTP 狀態碼，範圍從 2xx 成功碼到 4xx/5xx 錯誤碼。或者，可能會傳回服務定義的狀態碼，如 API 文件中所示。
- 視需要選擇性的其他標頭欄位來支援要求的回應，例如 Content-type 回應標頭。
選擇性 HTTP 回應訊息本文 欄位
- MIME 編碼的回應物件可能會在 HTTP 回應本文中傳回，例如來自傳回資料的 GET 方法的回應。這些通常會以結構化格式傳回為 JSON 或 XML，如回應標頭所 Content-type 指示。例如，從 Azure AD 要求存取權杖時，它會在回應本文中當做 access_token 元素傳回，這是資料收集中數個名稱/值配對物件的其中一個。在此範例中，也會包含的 Content-Type: application/json 回應標頭。

向 Azure AD 註冊用戶端應用程式

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

如果您使用未使用整合式 Azure AD 驗證的 REST API，或已經註冊用戶端，您可以跳至建立要求一節。

必要條件

用戶端應用程式必須在執行時間之前先讓 Azure AD 知道其身分識別設定，方法是在Azure AD 租使用者中註冊。以下是向 Azure AD 註冊用戶端之前要考慮的專案清單：

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

現在我們已準備好向 Azure AD 註冊用戶端應用程式。

用戶端註冊

若要註冊將存取 Azure Resource Manager REST API 的用戶端，請參閱使用入口網站建立可存取資源的 Active Directory 應用程式和服務主體，以取得逐步註冊指示。本文 (PowerShell 和 CLI 版本中也提供自動化註冊) 將示範如何：

向 Azure AD 註冊用戶端應用程式
設定許可權要求以允許用戶端存取 Azure Resource Manager API
設定 Azure Resource Manager的角色型存取控制 (RBAC) 設定，以授權用戶端

如需所有其他用戶端，請參閱整合應用程式與 Azure Active Directory。此文將示範如何：

在 [新增應用程式] 區段中，向 Azure AD 註冊用戶端應用程式
如果您要在 [更新應用程式] 區段中註冊 Web 用戶端) ，請建立秘密金鑰 (
在 [更新應用程式] 區段中，新增 API 所需的許可權要求

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

建立要求

本節涵蓋我們稍早討論的 5 個元件的前 3 個元件。首先，我們需要從 Azure AD 取得存取權杖，我們將用來組合要求訊息標頭。

取得存取權杖

一旦您擁有有效的用戶端註冊，基本上有 2 種方式可以與 Azure AD 整合，以取得存取權杖：

Azure AD 的平臺/語言中性 OAuth2 服務端點，這是我們將使用的端點。就像您使用的 Azure REST API 端點一樣，本節所提供的指示在使用 Azure AD 端點時，不會假設用戶端的平臺或語言/腳本;它只能傳送/接收來自 Azure AD 的 HTTPS 要求，並剖析回應訊息。
平臺/語言特定的 Microsoft 驗證程式庫 (MSAL) 。程式庫會提供 OAuth2 端點要求的非同步包裝函式，以及健全的權杖處理功能，例如快取和重新整理權杖管理。如需詳細資訊，包括參考檔、程式庫下載和範例程式碼，請參閱 Microsoft 驗證程式庫。

您將用來驗證用戶端並取得存取權杖的 2 個 Azure AD 端點稱為 OAuth2 /authorize 和 /token 端點。使用方式將取決於應用程式的註冊，以及您需要的 OAuth2 授權授與流程類型，才能在執行時間支援您的應用程式。針對本文的目的，我們將假設您的用戶端將使用下列其中一個授權授與流程：授權碼或用戶端認證。請遵循最符合案例的指示，以取得您將在其餘區段中使用的存取權杖。

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

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

首先，您的用戶端必須向 Azure AD 要求授權碼。如需 HTTPS GET 要求 /authorize 格式的詳細資料，請參閱要求授權碼，以及範例要求/回應訊息。 URI 將包含查詢字串參數，包括用戶端應用程式專屬的下列專案：
- client_id - 也稱為應用程式識別碼，這是您在上一節中註冊時指派給用戶端應用程式的 GUID
- redirect_uri - URL 編碼版本的 [其中一個] 在用戶端應用程式註冊期間指定的回復/重新導向 URI。請注意，您傳遞的值必須與註冊完全相符！
- resource - 您呼叫的 REST API 所指定的 URL 編碼識別碼 URI。 Web/REST API (也稱為資源應用程式，) 可以在其設定中公開一或多個應用程式識別碼 URI。例如：
  - Azure Resource Manager提供者 (和傳統服務管理) API 使用https://management.core.windows.net/
  - 如需任何其他資源，請參閱Azure 入口網站中的 API 檔或資源應用程式的組態。如需詳細資訊，identifierUris請參閱 Azure AD 應用程式物件的屬性。
對端點的要求 /authorize 會先觸發登入提示，以驗證使用者。您傳回的回應將會以重新導向 (302) 傳遞至您在中指定的 redirect_uri URI。回應標頭訊息將包含 location 欄位，其中包含重新導向 URI，後面接著 code 查詢參數，其中包含步驟 2 所需的授權碼。
接下來，您的用戶端必須兌換存取權杖的授權碼。如需 HTTPS POST 要求 /token 端點格式的詳細資料，以及範例要求/回應訊息，請參閱使用授權碼來要求存取權杖。因為這是 POST 要求，這次您會在要求本文中封裝應用程式特定參數。除了上述部分 (，以及其他新的) ，您還會傳遞：
- code - 這是查詢參數，其中包含您在步驟 1 中取得的授權碼。
- client_secret - 只有在用戶端設定為 Web 應用程式時，才需要此參數。這是您稍早在用戶端註冊中產生的相同秘密/金鑰值。

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

此授與只能供 Web 用戶端使用，允許應用程式直接存取資源， (使用者委派) 使用在註冊時提供的用戶端本身認證。非互動式用戶端通常會使用它 (沒有以精靈/服務身分執行的 UI) ，而且只需要 /token 端點才能取得存取權杖。

此授與的用戶端/資源互動與授權碼授與的步驟 #2 非常類似。如需端點 HTTPS POST 要求 /token 格式的詳細資料，以及範例要求/回應訊息，請參閱使用用戶端認證對服務呼叫的服務呼叫中的一節。

組合要求訊息

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

要求 URI

所有受保護的 REST 要求都需要 HTTPS 通訊協定的 URI 配置，並提供要求和回應與安全通道，因為敏感性資訊是傳輸/接收。此資訊 (例如：Azure AD 授權碼、存取/持有人權杖、敏感性要求/回應資料) 會由較低的傳輸層加密，以確保訊息的隱私權。

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

要求標頭

要求 URI 將會包含在要求訊息標頭中，以及您服務 REST API 規格和 HTTP 規格所決定的任何其他欄位。以下是您在要求中可能需要的一些常見標頭欄位：

Authorization：包含 OAuth2 持有人權杖來保護要求，如先前從 Azure AD 取得
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 要求方法可能會使用要求標頭 AND 本文欄位來傳送，如下所示：

PUT /subscriptions/03f09293-ce69-483a-a092-d06ea46dfb8c/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"
}

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

處理回應訊息

現在我們將完成 5 個元件的最後 2 個元件。

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

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

和回應本文，其中包含以 JSON 格式編碼的 Azure 訂用帳戶清單及其個別屬性，類似于：

{
    "value":[
        {
        "id":"/subscriptions/04f09293-ce69-583a-a091-z06ea46dfb8c",
        "subscriptionId":"04f09293-ce69-583a-a091-z06ea46dfb8c",
        "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/03f09293-ce69-483a-a092-d06ea46dfb8c/resourceGroups/ExampleResourceGroup",
    "name":"ExampleResourceGroup",
    "location":"westus",
    "properties":
        {
        "provisioningState":"Succeeded"
        }
}

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

就這麼簡單！一旦您註冊 Azure AD 應用程式，以及取得存取權杖並建立及處理 HTTP 要求的元件化技術，複寫您的程式碼即可利用新的 REST API。

如需應用程式註冊和 Azure AD 程式設計模型的詳細資訊，請參閱Microsoft 身分識別平臺 (適用于開發人員的 Azure Active Directory) ，包括 HowTo 和快速入門文章的完整索引，以及範例程式碼。
如需測試 HTTP 要求/回應，請參閱
- Fiddler。 Fiddler 是免費的 Web 偵錯 Proxy，可攔截 REST 要求，讓您輕鬆地診斷 HTTP 要求和回應訊息。
- JWT 解碼器和 JWT.io，可讓您在持有人權杖中快速且輕鬆地傾印宣告，以便驗證其內容。

請使用本文後面的 LiveFyre 批註區段來提供意見反應，並協助我們精簡並塑造我們的內容。

共用方式為