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

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，其中包括：{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 编码对象。对于 POST 或 PUT 操作，还应在 Content-type 请求标头中指定正文的 MIME 编码类型。某些服务要求使用特定的 MIME 类型，如 application/json。
HTTP 响应消息标头字段：
- HTTP 状态代码，包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。或者，可能返回服务定义的状态代码，如 API 文档中所指示。
- 可选的其他标头字段，用于支持请求的响应，例如 Content-type 响应标头。
可选的 HTTP 响应消息正文字段：
- 在 HTTP 响应正文中返回 MIME 编码的响应对象，例如来自返回数据的 GET 方法的响应。通常，这些对象以结构化格式（如 JSON 或 XML）返回，如 Content-type 响应标头所指示。例如，从 Microsoft Entra ID 请求访问令牌时，该令牌在响应正文中作为元素返回，该元素是access_token数据收集中多个名称/值配对对象之一。在此示例中，还包含的 Content-Type: application/json 响应标头。

使用 Microsoft Entra ID 注册客户端应用程序

大多数 Azure 服务 (（例如 Azure 资源管理器提供程序和经典部署模型）) 要求客户端代码使用有效凭据进行身份验证，然后才能调用服务的 API。身份验证通过Microsoft Entra ID在各个执行组件之间进行协调，并为客户端提供访问令牌作为身份验证证明。然后，令牌在后续 REST API 请求的 HTTP 授权标头中发送到 Azure 服务。令牌的声明还会向服务提供信息，使服务能够验证客户端并执行任何所需的授权。

如果使用的 REST API 不使用集成的Microsoft Entra身份验证，或者已注册客户端，请跳到创建请求部分。

先决条件

客户端应用程序必须通过在Microsoft Entra租户中注册，使其在运行时之前Microsoft Entra ID了解其标识配置。在向 Microsoft Entra ID 注册客户端之前，请考虑以下先决条件：

如果还没有Microsoft Entra租户，请参阅设置Microsoft Entra租户。
根据 OAuth2 授权框架，Microsoft Entra ID支持两种类型的客户端。了解每种情况有助于确定哪种方案最适合你的方案：
- Web/机密客户端在 Web 服务器上运行，可以访问其自己的标识下的资源 (例如服务或守护程序) ，或者获取已登录用户标识下访问资源的委派授权 (例如 Web 应用) 。只有 Web 客户端才能在Microsoft Entra身份验证期间安全地维护和提供自己的凭据，以获取访问令牌。
- 本机/公共客户端在设备上安装并运行。他们只能在委派授权下访问资源，使用已登录用户的标识代表用户获取访问令牌。
注册过程在注册应用程序的Microsoft Entra租户中创建两个相关对象：应用程序对象和服务主体对象。有关这些组件及其在运行时的使用方式的更多背景信息，请参阅 Microsoft Entra ID 中的应用程序和服务主体对象。

现在可以向 Microsoft Entra ID 注册客户端应用程序了。

客户端注册

若要注册访问 Azure 资源管理器 REST API 的客户端，请参阅使用门户创建可以访问资源的Microsoft Entra应用程序和服务主体。 (在 PowerShell 和 CLI 版本中也提供了用于自动注册) 文章介绍了如何：

向 Microsoft Entra ID 注册客户端应用程序。
设置权限请求以允许客户端访问 Azure 资源管理器 API。
配置 Azure 资源管理器 Role-Based 访问控制 (RBAC) 设置以授权客户端。

如果客户端访问 Azure 资源管理器 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 请求授权代码。有关对 /authorize 终结点的 HTTPS GET 请求的格式以及示例请求/响应消息的详细信息，请参阅请求授权代码。 URI 包含以下特定于客户端应用程序的查询字符串参数：
- client_id：在注册期间分配给客户端应用程序的 GUID，也称为应用程序 ID。
- redirect_uri：在注册客户端应用程序期间指定的回复/重定向 URI 之一的 URL 编码版本。传递的值必须与注册值完全匹配。
- resource：由你调用的 REST API 指定的 URL 编码标识符 URI。 Web/REST API (也称为资源应用程序) 可以在其配置中公开一个或多个应用程序 ID URI。例如：
  - Azure 资源管理器提供程序 (和经典部署模型) API 使用 https://management.core.windows.net/。
  - 有关任何其他资源，请参阅AZURE 门户中的 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 请求都需要 URI 方案的 HTTPS 协议，从而为请求和响应提供安全通道。信息 (，即Microsoft Entra授权代码、访问/持有者令牌和敏感请求/响应数据) 由较低传输层加密，确保消息的隐私性。

服务的请求 URI 的其余部分 (主机、资源路径和任何必需的查询字符串参数) 由其相关的 REST API 规范确定。例如，Azure 资源管理器提供程序 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 资源管理器提供程序发送 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/.../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;

并且应会收到一个响应正文，其中包含 Azure 订阅列表及其以 JSON 格式编码的单个属性，类似于：

{
    "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 操作。

资源管理器对每小时读取和写入请求数应用限制，以防止应用程序发送过多的请求。如果应用程序超出这些限制，请求将受到限制。响应标头包括作用域的剩余请求数。有关详细信息，请参阅限制资源管理器请求。

某些列表操作在响应正文中返回名为 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 是一个免费的 Web 调试代理，可以拦截 REST 请求，以便诊断 HTTP 请求/响应消息。
JWT.ms，这样可以快速轻松地将声明转储到持有者令牌中，以便验证其内容。

通过