對 Azure Stack Hub 提出 API 要求

發行項
12/01/2023

您可以使用 Azure Stack Hub REST API，將在 Azure Stack Hub 雲端新增虛擬機器 (VM) 之類的作業自動化。

使用 API 時，您的用戶端必須向 Microsoft Azure 登入端點進行驗證。端點會傳送權杖，以在每個傳送至 Azure Stack Hub API 的要求標頭中使用。 Microsoft Azure 使用 Oauth 2.0。

本文提供使用 cURL 公用程式建立 Azure Stack Hub 要求的範例。 cURL 是用於傳送資料且具有程式庫的命令列工具。這些範例將說明進行擷取權杖以存取 Azure Stack Hub API 的流程。大部分的程式設計語言都會提供 Oauth 2.0 程式庫，其具有健全的權杖管理，並會處理重新整理權杖之類的工作。

檢閱搭配一般 REST 用戶端 (例如 cURL) 使用 Azure Stack Hub REST API 的完整流程，可協助您了解基本要求，以及您預期會在回應承載中接收到的內容。

本文不會探索適用於擷取權杖的所有選項，例如互動式登入或建立專用的應用程式識別碼。如需這些主題的相關資訊，請參閱 Azure REST API 參考。

從 Azure 取得權杖

建立要求本文並使用內容類型 x-www-form-urlencoded 加以格式化，以取得存取權杖。將您的要求 POST 到 Azure REST 驗證和登入端點。

URI

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

租用戶識別碼可能是：

您的租用戶網域，例如 fabrikam.onmicrosoft.com
您的租用戶識別碼，例如 8eaed023-2b34-4da1-9baa-8bc8c9d6a491
租用戶獨立金鑰的預設值：common

張貼本文

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

針對每個值：

grant_type：
您將使用的驗證配置類型。在此範例中，值是 password。
資源：
權杖存取的資源。您可以藉由查詢 Azure Stack Hub 管理中繼資料端點來尋找資源。查看 audiences 區段。

Azure Stack Hub 管理端點：

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。

例如，使用 Azure Stack 開發套件 (ASDK) 作為端點：

curl 'https://management.local.azurestack.external/metadata/endpoints?api-version=2015-01-01'

回應：

{
"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"]
   }
}

範例 1

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

client_id

這個值會硬式編碼為預設值：

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

可供特定案例使用的替代選項：

Application	ApplicationID
LegacyPowerShell	0a7bdc5c-7b57-40be-9939-d4c5fc7cd417
PowerShell	1950a258-227b-4e31-a9cf-717495945fc2
WindowsAzureActiveDirectory	00000002-0000-0000-c000-000000000000
VisualStudio	872cd9fa-d31f-45e0-9eab-6e460a02d1f1
AzureCLI	04b07795-8ddb-461a-bbee-02f9e1bf7b46

username

例如，Azure Stack Hub Microsoft Entra帳戶：
```
azurestackadmin@fabrikam.onmicrosoft.com
```
password

Azure Stack Hub Microsoft Entra系統管理員密碼。

範例 2

要求：

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"

回應：

{
  "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 要求。若要將其新增為標頭，請以下列值建立授權標頭：Bearer <access token>。例如：

要求：

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

回應：

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 結構和查詢語法

一般要求 URI，包含：{URI-scheme} :// {URI-host} / {resource-path} ? {query-string}

URI 配置：
此 URI 表示用來傳送要求的通訊協定。例如，http 或 https。
URI 主機：
此主機會指定 REST 服務端點裝載所在伺服器的網域名稱或 IP 位址，例如 graph.microsoft.com 或 adminmanagement.local.azurestack.external。
資源路徑：
此路徑會指定資源或資源集合，其中可能包含服務用來判斷要選取哪些資源的多個區段。例如：beta/applications/00003f25-7e1f-4278-9488-efc7bac53c4a/owners 可用來查詢應用程式集合中特定應用程式的擁有者清單。
查詢字串：
此字串提供其他簡單參數，例如 API 版本或資源選取準則。

Azure Stack Hub 要求 URI 建構

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

URI 語法

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

查詢 URI 範例

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"

後續步驟

如需使用 Azure REST 端點的詳細資訊，請參閱 Azure REST API 參考。