向 Azure Stack Hub 发出 API 请求Make API requests to Azure Stack Hub

10/01/2020

可以使用 Azure Stack Hub REST API 自动执行操作，例如将虚拟机 (VM) 添加到 Azure Stack Hub 云。You can use the Azure Stack Hub REST APIs to automate operations such as adding a virtual machine (VM) to your Azure Stack Hub cloud.

Api 要求客户端向 Microsoft Azure 登录终结点进行身份验证。The APIs require your client to authenticate to the Microsoft Azure sign-in endpoint. 该终结点将返回一个要在发送到 Azure Stack Hub API 的每个请求的标头中使用的令牌。The endpoint returns a token to use in the header of every request sent to the Azure Stack Hub APIs. Microsoft Azure 使用 Oauth 2.0。Microsoft Azure uses Oauth 2.0.

本文提供了使用 cURL 实用工具创建 Azure Stack Hub 请求的示例。This article provides examples that use the cURL utility to create Azure Stack Hub requests. cURL 是一个命令行工具，它有一个用于传输数据的库。cURL is a command-line tool with a library for transferring data. 这些示例说明了检索令牌以访问 Azure Stack Hub API 的过程。These examples describe the process of retrieving a token to access the Azure Stack Hub APIs. 大多数编程语言都提供了 Oauth 2.0 库，这些库提供可靠的令牌管理，并可以处理刷新令牌等任务。Most programming languages provide Oauth 2.0 libraries, which have robust token management and handle tasks such as refreshing the token.

查看配合常规 REST 客户端（例如 cURL）使用 Azure Stack Hub REST API 的整个过程有助于了解基础请求，以及应可在响应有效负载中收到的内容。Review the entire process of using the Azure Stack Hub REST APIs with a generic REST client, such as cURL, to help you understand the underlying requests and what you can expect in a response payload.

本文并未探索可用于检索令牌的所有选项，例如交互式登录或创建专用应用 ID。This article does not explore all the options available for retrieving tokens, such as interactive sign-in or creating dedicated app IDs. 若要了解这些主题，请查看 Azure REST API 参考。For information about these topics, see the Azure REST API reference.

从 Azure 获取令牌Get a token from Azure

创建请求正文并使用内容类型 x-www-form-urlencoded 设置其格式，以获取访问令牌。Create a request body formatted using the content type x-www-form-urlencoded to obtain an access token. 使用 POST 将请求发布到 Azure REST 身份验证和登录终结点。POST your request to the Azure REST authentication and login endpoint.

URIURI

POST https://login.microsoftonline.com/{tenant id}/oauth2/token

租户 ID 为下列其中一项：Tenant ID is either:

租户域，例如 fabrikam.onmicrosoft.comYour tenant domain, such as fabrikam.onmicrosoft.com
租户 ID，例如 8eaed023-2b34-4da1-9baa-8bc8c9d6a491Your tenant ID, such as 8eaed023-2b34-4da1-9baa-8bc8c9d6a491
租户独立密钥的默认值：commonDefault value for tenant-independent keys: common

POST 正文Post Body

grant_type=password
&client_id=1950a258-227b-4e31-a9cf-717495945fc2
&resource=https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155
&username=admin@fabrikam.onmicrosoft.com
&password=Password123
&scope=openid

对于每个值：For each value:

grant_type：grant_type:
要使用的身份验证方案类型。The type of authentication scheme you'll use. 在此示例中，值为 password。In this example, the value is password.
资源：resource:
令牌访问的资源。The resource the token accesses. 可以通过查询 Azure Stack Hub 管理元数据终结点找到该资源。You can find the resource by querying the Azure Stack Hub management metadata endpoint. 查看“受众”**** 部分。Look at the audiences section.
Azure Stack Hub 管理终结点：Azure Stack Hub management endpoint:
```
https://management.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-01
```
备注

如果你是尝试访问租户 API 的管理员，请确保使用租户终结点，例如 https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011。If you are an admin trying to access the tenant API, make sure to use the tenant endpoint; for example, https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011.

例如，使用 Azure Stack 开发工具包作为终结点：For example, with the Azure Stack Development Kit as an endpoint:
```
curl 'https://management.local.azurestack.external/metadata/endpoints?api-version=2015-01-01'
```
响应：Response:
```
{
"galleryEndpoint":"https://adminportal.local.azurestack.external:30015/",
"graphEndpoint":"https://graph.windows.net/",
"portalEndpoint":"https://adminportal.local.azurestack.external/",
"authentication":{
   "loginEndpoint":"https://login.windows.net/",
   "audiences":["https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155"]
   }
}
```

示例Example

https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155

client_id****client_id

此值已硬编码为默认值：This value is hardcoded to a default value:

1950a258-227b-4e31-a9cf-717495945fc2

可供特定方案使用的替代选项：Alternative options are available for specific scenarios:

应用程序Application	ApplicationIDApplicationID
LegacyPowerShellLegacyPowerShell	0a7bdc5c-7b57-40be-9939-d4c5fc7cd4170a7bdc5c-7b57-40be-9939-d4c5fc7cd417
PowerShellPowerShell	1950a258-227b-4e31-a9cf-717495945fc21950a258-227b-4e31-a9cf-717495945fc2
WindowsAzureActiveDirectoryWindowsAzureActiveDirectory	00000002-0000-0000-c000-00000000000000000002-0000-0000-c000-000000000000
VisualStudioVisualStudio	872cd9fa-d31f-45e0-9eab-6e460a02d1f1872cd9fa-d31f-45e0-9eab-6e460a02d1f1
AzureCLIAzureCLI	04b07795-8ddb-461a-bbee-02f9e1bf7b4604b07795-8ddb-461a-bbee-02f9e1bf7b46

usernameusername

例如 Azure Stack Hub Azure AD 帐户：For example, the Azure Stack Hub Azure AD account:
```
azurestackadmin@fabrikam.onmicrosoft.com
```
passwordpassword

Azure Stack Hub Azure AD 管理员密码。The Azure Stack Hub Azure AD admin password.

示例Example

请求：Request:

curl -X "POST" "https://login.windows.net/fabrikam.onmicrosoft.com/oauth2/token" \
-H "Content-Type: application/x-www-form-urlencoded" \
--data-urlencode "client_id=1950a258-227b-4e31-a9cf-717495945fc2" \
--data-urlencode "grant_type=password" \
--data-urlencode "username=admin@fabrikam.onmicrosoft.com" \
--data-urlencode 'password=Password12345' \
--data-urlencode "resource=https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155"

响应：Response:

{
  "token_type": "Bearer",
  "scope": "user_impersonation",
  "expires_in": "3599",
  "ext_expires_in": "0",
  "expires_on": "1512574780",
  "not_before": "1512570880",
  "resource": "https://contoso.onmicrosoft.com/4de154de-f8a8-4017-af41-df619da68155",
  "access_token": "eyJ0eXAiOi...truncated for readability..."
}

API 查询API queries

获取访问令牌后，请将其作为标头添加到每个 API 请求。Once you get the access token, add it as a header to each of your API requests. 若要将其添加为标头，请创建值为 Bearer <access token> 的授权标头。To add it as a header, create an authorization header with the value: Bearer <access token>. 例如：For example:

请求：Request:

curl -H "Authorization: Bearer eyJ0eXAiOi...truncated for readability..." 'https://adminmanagement.local.azurestack.external/subscriptions?api-version=2016-05-01'

响应：Response:

offerId : /delegatedProviders/default/offers/92F30E5D-F163-4C58-8F02-F31CFE66C21B
id : /subscriptions/800c4168-3eb1-406b-a4ca-919fe7ee42e8
subscriptionId : 800c4168-3eb1-406b-a4ca-919fe7ee42e8
tenantId : 9fea4606-7c07-4518-9f3f-8de9c52ab628
displayName : Default Provider Subscription
state : Enabled
subscriptionPolicies : @{locationPlacementId=AzureStack}

URL 结构和查询语法URL structure and query syntax

通用请求 URI 包含：{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}Generic request URI, consists of: {URI-scheme} :// {URI-host} / {resource-path} ? {query-string}

URI 方案：URI scheme:
URI 指示用于发送请求的协议。The URI indicates the protocol used to send the request. 例如 http 或 https。For example, http or https.
URI 主机：URI host:
该主机指定 REST 服务终结点所在服务器的域名或 IP 地址，例如 graph.microsoft.com 或 adminmanagement.local.azurestack.external。The host specifies the domain name or IP address of the server where the REST service endpoint is hosted, such as graph.microsoft.com or adminmanagement.local.azurestack.external.
资源路径：Resource path:
该路径指定资源或资源集合，其中可能包含服务在确定选择这些资源时所用的多个段。The path specifies the resource or resource collection, which may include multiple segments used by the service in determining the selection of those resources. 例如：beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 可用于查询应用程序集合中特定应用程序的所有者列表。For example: beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners can be used to query the list a specific application's owners within the applications collection.
查询字符串：Query string:
该字符串提供其他简单参数，例如 API 版本或资源选择条件。The string provides additional simple parameters, such as the API version or resource selection criteria.

Azure Stack Hub 请求 URI 构造Azure Stack Hub request URI construct

{URI-scheme} :// {URI-host} / {subscription id} / {resource group} / {provider} / {resource-path} ? {OPTIONAL: filter-expression} {MANDATORY: api-version}

URI 语法URI syntax

https://adminmanagement.local.azurestack.external/{subscription id}/resourcegroups/{resource group}/providers/{provider}/{resource-path}?{api-version}

查询 URI 示例Query URI example

https://adminmanagement.local.azurestack.external/subscriptions/800c4168-3eb1-406b-a4ca-919fe7ee42e8/resourcegroups/system.local/providers/microsoft.infrastructureinsights.admin/regionhealths/local/Alerts?$filter=(Properties/State eq 'Active') and (Properties/Severity eq 'Critical')&$orderby=Properties/CreatedTimestamp desc&api-version=2016-05-01"

后续步骤Next steps

有关使用 Azure REST 终结点的详细信息，请参阅 Azure REST API 参考。For more information about using the Azure REST endpoints, see the Azure REST API Reference.

向 Azure Stack Hub 发出 API 请求Make API requests to Azure Stack Hub

从 Azure 获取令牌Get a token from Azure

URIURI

POST 正文Post Body

示例Example

示例Example

API 查询API queries

URL 结构和查询语法URL structure and query syntax

Azure Stack Hub 请求 URI 构造Azure Stack Hub request URI construct

URI 语法URI syntax

查询 URI 示例Query URI example

后续步骤Next steps

此页面有帮助吗?

反馈

此页面有帮助吗?