對 Azure Stack Hub 提出 API 要求Make API requests to Azure Stack Hub

您可以使用 Azure Stack Hub REST API,將在 Azure Stack Hub 雲端新增虛擬機器 (VM) 之類的作業自動化。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.

本文不會探索適用於擷取權杖的所有選項,例如互動式登入或建立專用的應用程式識別碼。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

租用戶識別碼可能是:Tenant ID is either:

  • 您的租用戶網域,例如 fabrikam.onmicrosoft.comYour tenant domain, such as fabrikam.onmicrosoft.com
  • 您的租用戶識別碼,例如 8eaed023-2b34-4da1-9baa-8bc8c9d6a491Your tenant ID, such as 8eaed023-2b34-4da1-9baa-8bc8c9d6a491
  • 租用戶獨立金鑰的預設值:commonDefault value for tenant-independent keys: common

張貼本文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_typegrant_type:
    您將使用的驗證配置類型。The type of authentication scheme you'll use. 在此範例中,值是 passwordIn 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. 查看 audiences 區段。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-011If 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:

    ApplicationApplication 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. 例如,httphttpsFor example, http or https.
  • URI 主機URI host:
    此主機會指定 REST 服務端點裝載所在伺服器的網域名稱或 IP 位址,例如 graph.microsoft.comadminmanagement.local.azurestack.externalThe 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.