Azure Stack Hub に対する API 要求を作成する

[アーティクル]
08/05/2024

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 ライブラリが用意されています。このライブラリでは、トークンの更新など、堅牢なトークン管理および処理タスクを行うことができます。

Azure Stack Hub REST API を cURL などの汎用 REST クライアントと共に使用するプロセス全体をレビューすることは、基になる要求と、期待できる応答ペイロードの内容を把握するのに役立ちます。

この記事では、対話型サインインなどのトークンの取得や専用アプリ ID の作成に使用できるすべてのオプションについては説明しません。これらのトピックに関する詳細については、Azure REST API リファレンスに関するページを参照してください。

Azure からトークンを取得する

コンテンツの種類 x-www-form-urlencoded を使用して書式設定された要求本文を作成し、アクセストークンを取得します。その要求を Azure REST 認証とログインエンドポイントに POST します。

URI

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

テナント ID は次のいずれかです。

テナントのドメイン (fabrikam.onmicrosoft.com など)
テナントの ID (8eaed023-2b34-4da1-9baa-8bc8c9d6a491 など)
テナント独立のキーの既定値: common

Post 本文

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 です。
resource:
トークンがアクセスするリソース。リソースを見つけるには、Azure Stack Hub 管理メタデータエンドポイントにクエリを実行します。 audiences セクションを確認します。

Azure Stack Hub 管理エンドポイント:

https://management.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-01

Note

管理者がテナント API へのアクセスを試みる場合は、必ずテナントエンドポイント (https://adminmanagement.{region}.{Azure Stack Hub domain}/metadata/endpoints?api-version=2015-01-011 など) を使用してください。

たとえば、エンドポイントとして Azure Stack Development Kit (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> を含むヘッダー authorization を作成します。次に例を示します。

要求:

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 リファレンスに関するページを参照してください。

次の方法で共有