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

Azure REST API 参考

欢迎使用 Azure REST API 参考文档。

表述性状态转移 (REST) API 是支持一组 HTTP 操作(方法)的服务终结点,它们提供针对服务资源的创建、检索、更新或删除访问权限。 本文介绍:

  • 如何使用 Postman 调用 Azure REST API
  • REST API 请求/响应对的基本组件。
  • 如何向 Microsoft Entra ID 注册客户端应用程序以保护 REST 请求。
  • 概述如何创建和发送 REST 请求,以及处理响应。

提示

大多数 Azure 服务 REST API 都有客户端库,这些库为使用 Azure 服务提供本机接口:

。网 | Java | | Node.jsPython | | C++

如何使用 curl 调用 Azure REST API

以下博客文章中所述的过程类似于 Postman 的过程,但演示了如何使用 curl 调用 Azure REST API。 可以考虑在无人参与的脚本中使用 curl,例如在 DevOps 自动化方案中。

通过 curl 调用 Azure REST API

REST API 请求/响应的组件

REST API 请求/响应对可分解为五个组件:

  1. 请求 URI,其中包括:{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 方法所需的其他可选的标头字段。 例如,提供持有者令牌的 Authorization 标头,其中包含请求的客户端授权信息。
  3. 可选的 HTTP 请求消息正文字段,用于支持 URI 和 HTTP 操作。 例如,POST 操作包含作为复杂参数传递的 MIME 编码对象。 对于 POST 或 PUT 操作,还应在 Content-type 请求标头中指定正文的 MIME 编码类型。 某些服务要求使用特定的 MIME 类型,如 application/json

  4. HTTP 响应消息标头字段

    • HTTP 状态代码,包括从 2xx 成功代码到 4xx 或 5xx 错误代码在内的各种代码。 或者,可能返回服务定义的状态代码,如 API 文档中所指示。
    • 可选的其他标头字段,用于支持请求的响应,例如 Content-type 响应标头。
  5. 可选的 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,请参阅:

完成客户端应用程序注册后,请转到创建 REST 请求并处理响应的客户端代码。

创建请求

本部分介绍前面讨论的五个组件中的前三个。 首先需要从 Microsoft Entra ID 获取访问令牌,该令牌用于汇编请求消息标头。

获取访问令牌

拥有有效的客户端注册后,可通过两种方式与 Microsoft Entra ID 集成以获取访问令牌:

  • 本文中使用的与平台和语言无关的 OAuth2 服务终结点。 使用 Microsoft Entra OAuth 终结点时,本节中提供的说明不假定客户端的平台或语言/脚本。 唯一的要求是可以向/从Microsoft Entra ID发送/接收 HTTPS 请求,并分析响应消息。
  • 特定于平台和语言的 Microsoft 身份验证库 (MSAL) ,这超出了本文的范围。 这些库为 OAuth2 终结点请求提供异步包装器,以及可靠的令牌处理功能,例如缓存和刷新令牌管理。 有关详细信息,请参阅 MICROSOFT 身份验证库概述 (MSAL)

用于对客户端进行身份验证和获取访问令牌的两个Microsoft Entra终结点称为 OAuth2 /authorize/token终结点。 如何使用它们取决于应用程序的注册以及运行时支持应用程序所需的 OAuth2 授权流 类型。 在本文中,我们假设客户端使用以下授权流之一:授权代码或客户端凭据。 若要获取其余部分中使用的访问令牌,请按照与方案最匹配的流的说明进行操作。

授权代码授予 (交互式客户端)

此授权由 Web 客户端和本机客户端使用,需要已登录用户的凭据才能将资源访问权限委托给客户端应用程序。 它使用 /authorize 终结点获取 (的授权代码,以响应用户登录/同意) ,然后使用 /token 终结点来交换访问令牌的授权代码。

  1. 首先,客户端需要从 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/
      • 有关任何其他资源,请参阅 API 文档或Azure 门户中的资源应用程序的配置。 有关详细信息,请参阅 identifierUris Microsoft 图形 API 应用程序对象的 属性。

    /authorize 终结点的请求首先触发登录提示来对用户进行身份验证。 返回的响应以重定向 (302) 传递到中指定的 redirect_uriURI。 响应标头消息包含字段 location ,其中包含重定向 URI, code 后跟查询参数。 参数 code 包含步骤 2 所需的授权代码。

  2. 接下来,客户端需要兑换访问令牌的授权代码。 有关对 /token 终结点的 HTTPS POST 请求格式和请求/响应示例的详细信息,请参阅 请求访问令牌。 由于这是 POST 请求,因此请在请求正文中打包特定于应用程序的参数。 除了前面提到的一些参数 (以及其他) 的新参数外,还将传递:

    • code:此查询参数包含你在步骤 1 中获取的授权代码。

    • client_secret:仅当客户端配置为 Web 应用程序时,才需要此参数。 这是前面在 客户端注册中生成的相同机密/密钥值。

客户端凭据授予非交互式客户端 ()

此授权仅由 Web 客户端使用,允许应用程序直接访问资源, (用户委托) 使用注册时提供的客户端凭据。 授权通常由非交互式客户端使用, (没有作为服务或守护程序运行的 UI) 。 它只需要 /token 终结点即可获取访问令牌。

此授权的客户端/资源交互类似于授权代码授予的步骤 2。 有关对/token终结点的 HTTPS POST 请求格式和请求/响应示例的详细信息,请参阅 Microsoft 标识平台 和 OAuth 2.0 客户端凭据流中的“获取令牌”部分。

组合请求消息

大多数编程语言或框架和脚本环境使汇编和发送请求消息变得容易。 它们通常提供一个 Web/HTTP 类或 API 来抽象化请求的创建或格式设置,以便更轻松地 (HttpWebRequest.NET Framework中的类编写客户端代码,例如) 。 为简洁起见,由于大部分任务都是为你处理的,本部分仅介绍请求的重要元素。

请求 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,这样可以快速轻松地将声明转储到持有者令牌中,以便验证其内容。