你当前正在访问 Microsoft Azure Global Edition 技术文档网站。如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站，请访问 https://docs.azure.cn。

Azure REST API 参考

项目
07/19/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，其中包括：{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}。请注意，我们在此处单独调用，因为大多数语言/框架都要求你从请求消息中单独传递它，但它实际上包含在请求消息标头中。
- 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 方法所需的可选附加标头字段。例如，提供持有者令牌的 Authorization 标头，其中包含请求的客户端授权信息。
可选的 HTTP 请求消息正文字段，用于支持 URI 和 HTTP 操作。例如，POST 操作包含作为复杂参数传递的 MIME 编码对象。对于 POST/PUT 操作，还应在请求标头中 Content-type 指定正文的 MIME 编码类型。请注意，某些服务要求使用特定的 MIME 类型，例如 application/json。
HTTP 响应消息标头 字段
- HTTP 状态代码，范围从 2xx 成功代码到 4xx/5xx 错误代码。或者，可能返回服务定义的状态代码，如 API 文档中所指示。
- 支持请求响应所需的可选附加标头字段，例如 Content-type 响应标头。
可选的 HTTP 响应消息正文 字段
- 可以在 HTTP 响应正文中返回 MIME 编码的响应对象，例如来自返回数据的 GET 方法的响应。通常，它们将以 JSON 或 XML 的形式以结构化格式返回，如响应标头所示 Content-type 。例如，从 Azure AD 请求访问令牌时，该令牌将在响应正文中作为元素返回，该元素是 access_token 数据收集中多个名称/值配对对象之一。在此示例中，还将包含的 Content-Type: application/json 响应标头。

将客户端应用程序注册到 Azure AD

大多数 Azure 服务 (（例如 Azure 资源管理器提供程序和经典服务管理 API) 要求客户端代码使用有效凭据进行身份验证，然后才能调用服务的 API。身份验证由 Azure AD 在各个参与者之间进行协调，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 应用) 。只有 Web 客户端才能在 Azure AD 身份验证期间安全地维护和提供自己的凭据，以获取访问令牌。
- 在设备上安装/运行的本机/公共客户端 (，) 只能在委派授权下访问资源，使用已登录用户的标识代表用户获取访问令牌。
注册过程将在注册应用程序的 Azure AD 租户中创建 2 个相关对象：应用程序对象和服务主体对象。有关这些组件及其在运行时的使用方式的更多背景信息，请查看 Azure Active Directory 中的应用程序和服务主体对象。

现在，我们已准备好将客户端应用程序注册到 Azure AD。

客户端注册

若要注册将访问 Azure 资源管理器 REST API 的客户端，请参阅使用门户创建可访问资源的 Active Directory 应用程序和服务主体，了解分步注册说明。本文 (在 PowerShell 和 CLI 版本中也提供，用于自动注册) 将演示如何：

将客户端应用程序注册到 Azure AD
设置权限请求以允许客户端访问 Azure 资源管理器 API
配置 Azure 资源管理器的基于角色访问控制 (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 请求授权代码。有关对/authorize终结点的 HTTPS GET 请求格式的详细信息，以及示例请求/响应消息，请参阅请求授权代码。 URI 将包含查询字符串参数，包括特定于客户端应用程序的以下参数：
- client_id - 也称为应用程序 ID，这是在上述部分中注册时分配给客户端应用程序的 GUID
- redirect_uri - 在注册客户端应用程序期间指定的回复/重定向 URI 的 [之一] 的 URL 编码版本。请注意，传递的值必须与注册完全匹配！
- resource - 由调用的 REST API 指定的 URL 编码标识符 URI。 (也称为资源应用程序的 Web/REST API) 可以在其配置中公开一个或多个应用程序 ID URI。例如：
  - Azure 资源管理器提供程序 (和经典服务管理) API 的使用https://management.core.windows.net/
  - 有关任何其他资源，请参阅 API 文档或Azure 门户中的资源应用程序的配置。有关更多详细信息，identifierUris另请参阅 Azure AD 应用程序对象的属性。
对 /authorize 终结点的请求将首先触发登录提示，以便对最终用户进行身份验证。返回的响应将以重定向 (302) 传递到中指定的 redirect_uriURI。响应标头消息将包含一个 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 请求都需要 URI 方案的 HTTPS 协议，为请求和响应提供安全通道，因为敏感信息是传输/接收的。此信息 (即：Azure AD 授权代码、访问/持有者令牌、敏感请求/响应数据) 由较低的传输层加密，从而确保消息的隐私性。

服务的请求 URI (主机、资源路径以及) 的任何必需查询字符串参数的其余部分将由其相关的 REST API 规范确定。例如，Azure 资源管理器提供程序 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 资源管理器提供程序的 HTTPS GET 请求方法可能会使用类似于下面的请求标头字段发送，但请注意，请求正文为空：

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

<no body>

Azure 资源管理器提供程序的 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;

和响应正文，其中包含以 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) ，包括操作方法文章和快速入门文章的综合索引以及示例代码。
若要测试 HTTP 请求/响应，请检查输出
- 菲德勒 Fiddler 是一个免费的 Web 调试代理，可以截获 REST 请求，以便轻松诊断 HTTP 请求和响应消息。
- JWT 解码器和 JWT.io，使你能够快速轻松地将声明转储到持有者令牌中，以便验证其内容。

请使用本文后面的 LiveFyre 评论部分提供反馈，帮助我们优化和塑造内容。