Azure にリソースをデプロイしたり、設定を変更する際には Azure REST API が使われる。PowerShell や Azure CLI はこれらの API をラップしている。どのようなケースで Azure REST API をそのまま使用するのだろうか？

最新の API を使用したい場合
API の挙動を理解したい場合

PowerShell, Azure CLI、各種の Azure SDK はすべての API をサポートしているわけではない。Azure に対して操作を行いたいときに、APIには存在するのに、PowerShell などが対応していないケースも多い。
そのようなケースでも、REST API を使えば問題なくアクセスできる。また、インターネットのブログや、ドキュメントの情報が古い場合もあるが、REST API を見てみれば現在の状況がわかるので、最も信頼性の高いリソースといえる。

REST API を CLIやSDK経由ではなく、素で使用することで、どのような仕様になっているのか、どのような挙動になっているかを理解できる。Azure のリソースに対するプログラミングをする場合、仕様と挙動を理解することにより正確さとスピードを向上させることができる。

2 つのフロー

Azure REST API にアクセスするには、以下のいずれかのフローを使って、トークンを取得する必要がある。

OAuth 2.0 Code glant flow
OAuth 2.0 Client credentials flow

最初の Flow は、Web ブラウザを使って認証を行いトークンを発行する方法であり、２つ目の Flow は、クライアントのクレデンシャルで認証する方法である。今回は Postman を使うので、あまり Web Browser を使いたくない。自動で接続してほしい。ユーザのインタラクションを必要せずに、トークンが欲しい場合は Client credentials flow を使うとよい。今回のユースケースでは、Client credentials の Flow がフィットしているのでそちらで検証する。

Azure REST API を使用するステップ

Azure REST API を使用するには次の３つのステップが必要になる

Service Principal の作成
Token の取得
REST API の呼び出し

また、Token が Expire した場合は、 code grant flow だと refresh token を使うが、このフローでは、リフレッシュはないため、再度トークンを取得すればよい。

Service Principal の作成

Postman から Azure REST API にアクセスするために、クライアントクレデンシャルを事前に Azure AD に登録しておく必要がある。クライアントを表す Application、そしてService Principal という、クライアントが、どのような権限で対象のリソースにアクセスできるかを割り当てるオブジェクトの２つを作る必要がある。それらを作り、Application に設定したクレデンシャル (Password や証明書)を使うと、Azure のリソースにアクセスできるようになる。

具体的な方法として最も簡単なのは、Azure CLI を用いる方法だろう。Azure CLI を入れていない人はインストールをお勧めする。

az ad sp create-for-rbac --name ServicePrincipalName

上記のコマンドを実行すると、自動で Application と Service Principal を作成してくれる。さらに、設定に必要な項目だけを返してくれる。

>az ad sp create-for-rbac --name ABCDE
{
  "appId": "c5c23df7-0ad6-4a1d-8a7c-64a5b3336b77",
  "displayName": "ABCDE",
  "name": "http://ABCDE",
  "password": "ef89fc9b-64e3-4f3d-8440-386d5472a33e",
  "tenant": "99f722bf-77f3-52ab-99ab-2d7cd011db43"
}

この一番簡単な方法で Application と Service Principal を作ると、あなたのサブスクリプションのすべてのリソースにアクセス可能な、Service Principal ができてしまうので注意が必要だ。制限をかけたい場合は次のリンクを参照されたい。上記のサンプルはでたらめのデータなので、上記の情報で次に述べるTokenの取得のAPIにアクセスしても権限がなく 401でエラーになる。

Create an Azure service principal with Azure CLI 2.0

Token の取得

Service Principal を取得したのち、アクセストークンを取得するためにリクエストを投げる。

https://login.microsoftonline.com/{{tenantId}}/oauth2/token の {{tenantId}} を先ほどの Service Prinipal の tenat で埋めて、POST のリクエストと次の値を、x-www-form-urlencoded の形式で、POST の BODY として送信する。

Name	Description	sample
URL	Endpoint	https://login.microsoftonline.com/{{tenantId}}/oauth2/token
Method	Request Method	POST
grant_type	client_credentials 固定	client_credentials
client_id	Application Id	c5c23df7-0ad6-4a1d-8a7c-64a5b3336b77
client_secret	Secret (password)	ef89fc9b-64e3-4f3d-8440-386d5472a33e
resource	Target Resource	https://management.azure.com/

上記のリクエストを投げると、access token が access_token という名前で返ってくる。

{
    "token_type": "Bearer",
    "expires_in": "3599",
    "ext_expires_in": "0",
    "expires_on": "1536978531",
    "not_before": "1536974631",
    "resource": "https://management.azure.com/",
    "access_token": "eyJ0eX....."
}

REST の呼び出し

REST API を呼ぶときに先ほど獲得した access_token をヘッダに渡してあとは、仕様通りにREST API をコールするとよい。access_token は JWT token の形式になっている。

Header

Azure REST API に必要なヘッダは次の通り

name	description	sample
Content-Type	Content Type。application/json である必要がある	application/json
Authorization	Bearer トークン。	Bearer eyJ0eX....

URL

URL の形式は次の通り。当然のことだが、API のバージョンによって使える内容が異なるので、最新のバージョンを見てみるとよい。

https://management.azure.com//subscriptions/{{subscriptionId}}/resourceGroup/{{resourceGroupName}}/providers/{{ResourceProvider}}/{{resourceType}}/{{ResourceName}}/{{optional}?api-version={{api-version}}

概念の説明

API の概念としては、次の階層になっている。

Subscription
Resource Group
Resource Provider
Resource Type
API Version

Azure REST API の classic ではないのものは、ARM API とも呼ばれる。ARM API は Rsource Group の単位でリソースを管理する。リソースは、Resource Provider から割り当てられる。各リソースは複数の API バージョンを持っている。

Resource Provider

Resource Provider はリソースのプロバイダで、次の PowerShell Command let でどのようなものが使えるかを取得できる。

 Get-AzureRmResourceProvider | `
>> Select-Object ProviderNamespace, ResourceTypes |`
>> Sort-Object ProviderNamespace

ProviderNamespace               ResourceTypes
-----------------               -------------
Microsoft.ADHybridHealthService {services, addsservices, configuration, operations...}
Microsoft.Advisor               {suppressions, configurations, recommendations, generateRecommendations...}
Microsoft.ApiManagement         {service, validateServiceName, checkServiceNameAvailability, checkNameAvailability...}
Microsoft.Authorization         {roleAssignments, roleDefinitions, classicAdministrators, permissions...}

Resource Type

Resource Provider には、各種のリソースタイプが存在し、それ毎にリクエストを投げることができる。各リソースタイプは、サブスクリプションによって使えるリージョンが異なってくる。また、いくつかのリソースタイプは、リソースの使用にあたって、Registration が必要になることがある。

Get-AzureRmResourceProvider -ProviderNamespace Microsoft.Comput
e |`
>> Select-Object ResourceTypes, Locations | `
>> Sort-Object ResourceTypes

ResourceTypes                                               Locations
-------------                                               ---------
{virtualMachines/diagnosticSettings}                        {East US, East US 2, West US, Central US...}
{virtualMachines/metricDefinitions}                         {East US, East US 2, West US, Central US...}
{sharedVMImages}                                            {West Central US, South Central US, East US 2, Southeast...
{restorePointCollections/restorePoints}                     {Southeast Asia, East US 2, Central US, West Europe...}
{locations/publishers}                                      {East US, East US 2, West US, Central US...}

バージョンの取得

リソースプロバイダ毎に使用できる API バージョンを取得するためには、次の PowerShell を実行するとよい。

 ((Get-AzureRmResourceProvider -ProviderNamespace Microsoft.Web)
.ResourceTypes | Where-Object {$_.ResourceTypeName -eq 'sites'}).ApiVersions

2018-02-01
2016-08-01
2016-03-01
2015-08-01-preview
2015-08-01
2015-07-01
  :

REST API のサンプル

リソースの構造は対象リソースによって異なる。たとえば WebApp の Config のパートなら下記の通り。

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Web/sites/{name}/config/web?api-version=2016-08-01

詳細はこちらのページでAPIを確認するとよい。