Azure REST API 參考

歡迎使用 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個元件:

  1. {URI-scheme} :// {URI-host} / {resource-path} ? {query-string} 所組成的 要求 URI。 請注意,我們會在這裡另外呼叫這一點,因為大部分的語言/架構都要求您將它與要求訊息分開傳遞,但實際上會包含在要求訊息標頭中。
    • URI 配置:表示用來傳輸要求的通訊協定。 例如,httphttps
    • URI 主機:裝載 REST 服務端點之伺服器的功能變數名稱或 IP 位址,例如 graph.microsoft.com
    • 資源路徑:指定資源或資源集合,其中可能包含服務用來判斷這些資源選取範圍的多個區段。 例如: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 可以用來查詢應用程式集合中特定應用程式的擁有者清單。
    • 查詢字串 (選擇性) :用來提供額外的簡單參數,例如 API 版本、資源選取準則等等。
  2. HTTP 要求訊息標頭 欄位
    • 必要的 HTTP 方法 (也稱為作業或動詞) ,它會告訴服務您所要求的作業類型。 Azure REST Api 支援 GET、HEAD、PUT、POST 和 PATCH 方法。
    • 指定的 URI 和 HTTP 方法所需的選擇性額外標頭欄位。 例如,提供持有人權杖的授權標頭,其中包含要求的用戶端授權資訊。
  3. 選擇性的 HTTP 要求訊息主體 欄位,以支援 URI 和 HTTP 作業。 例如,POST 作業包含以複雜參數形式傳遞的 MIME 編碼物件。 您也應該在 Content-type 要求標頭中,針對 POST/PUT 作業,指定主體的 MIME 編碼類型。 請注意,某些服務會要求您使用特定的 MIME 類型,例如 application/json
  4. HTTP 回應訊息標頭 欄位
    • HTTP 狀態碼,範圍從2xx 成功碼到 4xx/5xx 錯誤碼。 或者,可能會傳回服務定義的狀態碼,如 API 文件中所示。
    • 支援要求的回應所需的選擇性額外標頭欄位,例如 Content-type 回應標頭。
  5. 選擇性 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 伺服器上執行) 可以用自己的身分識別來存取資源 (ie: service/daemon) ,或取得委派的授權,以在登入使用者的身分識別下存取資源 (ie: web 應用程式) 。 只有 web 用戶端能夠在 Azure AD authentication 期間安全地維護和呈現其本身的認證,以取得存取權杖。
    • (在裝置上安裝/執行的原生/公用用戶端) 只能使用已登入使用者的身分識別,來存取委派授權下的資源,以代表使用者取得存取權杖。
  • 註冊程式會在已註冊應用程式的 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 要求,以及剖析回應訊息。
  • (ADAL) 的平臺/語言特定 Azure AD 驗證程式庫。 這些程式庫提供 OAuth2 端點要求的非同步包裝函式,以及強大的權杖處理功能,例如快取和重新整理權杖管理。 如需詳細資訊(包括參考檔、程式庫下載和範例程式碼),請參閱Azure Active Directory Authentication 程式庫

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

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

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

  1. 首先,您的用戶端必須向 Azure AD 要求授權碼。 如需端點的 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/
      • 如需其他資源,請參閱 Azure 入口網站中的 API 檔或資源應用程式的設定。 如需詳細資訊,另請參閱 Azure AD 應用程式物件的 identifierUris 屬性

    端點的要求 /authorize 會先觸發登入提示,以驗證使用者。 您取回的回應將會以重新導向的形式傳遞 (302) 至您在中指定的 URI redirect_uri 。 回應標頭訊息將會包含一個 location 欄位,其中包含重新導向 URI,後面接著 code 查詢參數,其中包含步驟 #2 所需的授權碼。

  2. 接下來,您的用戶端必須兌換授權碼以取得存取權杖。 請參閱 使用授權碼來要求存取權杖 ,以取得端點的 HTTPS POST 要求格式的詳細資料 /token ,以及範例要求/回應訊息。 因為這是 POST 要求,所以這次您會將應用程式特定參數封裝在要求主體中。 除了以上所述的部分 (,還有其他新的) ,您將會傳遞:

    • code -這是查詢參數,其中將包含您在步驟 #1 中取得的授權碼。
    • client_secret -如果您的用戶端設定為 web 應用程式,您將只需要此參數。 這是您稍早在 用戶端註冊中所產生的相同秘密/金鑰值。

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

這項授與只能由 web 用戶端使用,讓應用程式可以直接存取資源 (不需使用用戶端自己的認證,) 使用註冊時提供的認證。 它通常是由非互動式用戶端使用 (沒有任何 UI) 以 daemon/服務的形式執行,而且只需要 /token 端點取得存取權杖。

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

組合要求訊息

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

要求 URI

所有安全的 REST 要求都需要 HTTPS 通訊協定來進行 URI 配置,以提供安全通道的要求和回應,因為機密資訊是傳輸/接收的事實。 這項資訊 (ie: 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 要求方法可能會使用要求標頭和主體欄位來傳送,如下所示:

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;

以及包含 Azure 訂用帳戶清單及其以 JSON 格式編碼之個別屬性的回應主體,類似于:

{
    "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 範例中,我們應該會收到類似下列的回應標頭,確認 PUT 作業新增 ">exampleiothubname" 成功:

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 狀態碼,如果 succsessful,則根據 API 規格 (或 Content-TypeContent-Length 回應標頭欄位) 來剖析回應主體。

大功告成! 一旦您註冊 Azure AD 應用程式,並使用元件化技術來取得存取權杖,以及建立和處理 HTTP 要求,就很容易就能複寫您的程式碼,以利用新的 REST Api。

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

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