こんにちは。

以前投稿した「Azure Resource Manager の template の How-to」では、Template を使って宣言的 (Declarative) に Azure Resource を定義する手法を紹介しましたが、今回は、Azure Resource Manager (ARM) の REST API を使って命令型 (Imperative) で処理する方法を紹介します。

XML ベースの Azure Service Management 時代も REST API による管理が可能でしたが、新しい ARM (Azure Resource Manager) による REST API では、上述の Json フォーマットの Template と Symmetry な関係になっており、Template を扱ったことがあるエンジニアならすぐに扱えるようになっています。

User の Role 割り当て (RBAC)

このあと User で (OAuth による) Login をおこなって REST API を呼び出しますが、Azure Resource Manager (ARM) の権限 (ACL) 管理では RBAC (Role Base Access Control) を使用します。
このため、あらかじめ、ユーザーに対して Role を付与しておきます。

補足 : 後述の通り、現状は (2015/09 現在は) Azure AD の User を使用する必要があるので、Microsoft Account で管理をおこなっている場合には、必ずこの設定を事前におこなっておいてください。

例えば、今回扱う Resource Group (ResourceGroup01 と仮定します) に対して参照・更新などの権限を付与するには、まず、Azure Portal で対象の Resource Group を表示して、下図の [Access] アイコン [Access control (IAM)] メニューをクリックします。

表示される RBAC の設定画面で、(Azure AD の) User に Contributor の Role を割り当てれば完了です。
なお、参照 (GET) の操作のみで充分なら、Reader の Role を割り当てます。
(Windows PowerShell などコマンドを使った設定も可能です。)

Role は、Subscription、Resource Group、Resource の各単位で設定可能で、継承されますので、例えば、Subscription 単位で Contributor として設定すれば、その中のすべての Resource Group に対して Contributor が付与されます。(以前の「共同管理者」に似た権限付与をしたい場合は、このように設定すると良いでしょう。)

認証 (Authentication)

REST API を使用するために必要な Access Token を取得するには、現時点 (2015/09) では「Native Application で Azure AD に Login するプログラミング (OAuth 紹介)」で紹介した OAuth のフローを実装します。

まず、Azure AD の管理画面 (Azure Management Portal) で Application を登録します。(登録方法は「Native Application で Azure AD に Login するプログラミング (OAuth 紹介)」を参照してください。)
この際、現時点は、下図の通り、Azure Service Management 用の Permission 設定してください。(現在は、Azure Management Portal を使った Service Management API 用の設定をおこないます。)

あとは、下記の通り、「Native Application で Azure AD に Login するプログラミング (OAuth 紹介)」で紹介したフローで Access Token を取得します。

(1) Browser または Browser Component (Native App の場合) で下記 URI にアクセスすると、SignIn 画面が表示されるので、上記で権限付与した User の ID / Password を入力してログインします。
なお下記の通り、現在は、resource として https://management.azure.com/ を指定しておいてください。(将来、https://management.azure.com/{scope name} が使用できるようになるでしょう。)

GET https://login.microsoftonline.com/common/oauth2/authorize  ?response_type=code  &client_id={client id}  &resource=https%3a%2f%2fmanagement.azure.com%2f  &redirect_uri={redirect uri}

(2) ログインをおこなうと、上記で指定した redirect uri に code が付与されて返ってきます。例えば、redirect uri が https://localhost/test の場合、以下のような URL に戻されます。
この code を取得します。

https://localhost/test?code=AAABAAA...

(3) 上記で取得した code を使って、下記の POST 要求を投げます。(今回は Web アプリの場合のサンプルです。Native アプリの場合、client secret は使用しないでください。)

POST https://login.microsoftonline.com/common/oauth2/tokenContent-Type: application/x-www-form-urlencodedgrant_type=authorization_code&code={previous code}&client_id={client id}&client_secret={client secret}&redirect_uri={redirect uri}

(4) 上記の POST 要求の結果として、下記の通り access token が返ってきます。以降の REST API で、この access token を使用します。

HTTP/1.1 200 OK{  "expires_in": "3599",  "token_type": "Bearer",  "scope": "user_impersonation",  "expires_on": "1441770794",  "not_before": "1441766894",  "resource": "https://management.azure.com/",  "access_token": "eyJ0eXA...",  "refresh_token": "AAABAAA...",  "id_token": "eyJ0eXA..."}

Azure Resource Manager (ARM) REST API による CRUD 操作

では、上記で取得した access token を使用して、Azure Resource Manager の REST API を実行してみましょう。

例えば、Virtual Machine resource の情報を取得 (GET) するには、以下の通り要求します。(URI は、以降、いくつか改行して記載しています。。。)

GET https://management.azure.com/subscriptions  /{subscription id}/resourceGroups/{resource group name}  /providers/Microsoft.Compute/virtualMachines  /{virtual machine resource name}?api-version={api version}Accept: application/jsonAuthorization: Bearer {access token}

例えば、Id が「af254894-bed5-44c5-9f6b-288427de57c1」の Subscription の、「ResourceGroup01」という名前の Resource Group にある、「testmachine01」という名前の Virtual Machine の場合は、以下の通りです。
access token には、上記で取得した値を設定します。

GET https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups  /ResourceGroup01/providers/Microsoft.Compute  /virtualMachines/testmachine01  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...

この結果として、以下の通り Virtual Machine の内容が返ってきます。(「Azure Resource Manager の template の How-to」で解説した Template と同じ構造の内容が返されます。)

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "properties": {    "hardwareProfile": {      "vmSize": "Basic_A1"    },    "storageProfile": {      "imageReference": {        "publisher": "MicrosoftWindowsServer",        "offer": "WindowsServer",        "sku": "2012-R2-Datacenter",        "version": "latest"      },      "osDisk": {        "osType": "Windows",        "name": "testdisk01",        "createOption": "FromImage",        "vhd": {          "uri": "http://tsmatsuzteststorage01.blob.core.windows.net/vhds/test01.vhd"        },        "caching": "ReadWrite"      },      "dataDisks": []    },    "osProfile": {      "computerName": "mycomputer01",      "adminUsername": "demouser",      "windowsConfiguration": {        "provisionVMAgent": true,        "enableAutomaticUpdates": true      },      "secrets": []    },    "networkProfile": {      "networkInterfaces":[        { "id":"/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Network/networkInterfaces/testnic01" }       ]    },    "provisioningState": "Succeeded"  },  "id": "/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Compute/virtualMachines/testmachine01",  "name": "testmachine01",  "type": "Microsoft.Compute/virtualMachines",  "location": "eastus",  "tags": {    "displayName": "testmachine01"  }}

更新 Action (作成・変更・削除) も可能です。
例えば、上記 Virtual Machine の vmSize を変更する場合は、下記の通りです。(下記で location は必須ですが、この値は変更できないので注意してください。)

HTTP Request

PUT https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups  /ResourceGroup01/providers/Microsoft.Compute  /virtualMachines/testmachine01  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...Content-Type: application/json; charset=utf-8{  "location": "East US",  "properties":  {    "hardwareProfile":    {      "vmSize": "Basic_A2"    }  }}

HTTP Response

HTTP/1.1 200 OKAzure-AsyncOperation: https://management.azure.com/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Compute/locations/eastus/operations/c5bf0c44-d8d8-4ef0-ae5b-8f9748e108b1?api-version=2015-05-01-preview{  "properties": {    "hardwareProfile": {      "vmSize": "Basic_A2"    },    "storageProfile": {      "imageReference": {        "publisher": "MicrosoftWindowsServer",        "offer": "WindowsServer",        "sku": "2012-R2-Datacenter",        "version": "latest"      },      "osDisk": {        "osType": "Windows",        "name": "testdisk01",        "createOption": "FromImage",        "vhd": {          "uri": "http://tsmatsuzteststorage01.blob.core.windows.net/vhds/test01.vhd"        },        "caching": "ReadWrite"      },      "dataDisks": []    },    "osProfile": {      "computerName": "mycomputer01",      "adminUsername": "demouser",      "windowsConfiguration": {        "provisionVMAgent": true,        "enableAutomaticUpdates": true      },      "secrets": []    },    "networkProfile": {"networkInterfaces":[{"id":"/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Network/networkInterfaces/testnic01"}]},    "provisioningState": "Updating"  },  "id": "/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Compute/virtualMachines/testmachine01",  "name": "testmachine01",  "type": "Microsoft.Compute/virtualMachines",  "location": "eastus",  "tags": {    "displayName": "testmachine01"  }}

なお、上述の通り、例えば、Reader の Role しか付与されていないユーザーで上記の操作 (PUT) をおこなうと、下記の RBAC による権限エラーが返されます。

HTTP/1.1 403 ForbiddenContent-Type: application/json; charset=utf-8{  "error": {    "code": "AuthorizationFailed",    "message": "The client 'demouser02@demo.onmicrosoft.com' with object id '3da21de1-17b0-42e8-a20c-8d330ede1127' does not have authorization to perform action 'Microsoft.Compute/virtualMachines/write' over scope '/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Compute/virtualMachines/testmachine01'."  }}

「Azure Resource Manager の template の How-to」で解説した Template の構成と比較すると、ARM の REST API は下記の構成になっているのがわかります。

Azure Resource Manager (ARM) REST API による Action

さて、ここまでだと、Template で可能なことを REST に変えただけと思われるかもしれませんが、ARM の REST API は OData v4 に対応しているため CRUD 以外の Action も実行できます。

例えば、Azure Resource Manager (ARM) を使った Virtual Machine (VM) の Stop, Generalize, Capture の流れを、下記の通り、REST API のみを使って簡単に操作できます。

Stop の Http Request

POST https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups  /ResourceGroup01/providers/Microsoft.Compute  /virtualMachines/testmachine01/powerOff  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...

Stop の Http Response

HTTP/1.1 202 AcceptedLocation: https://management.azure.com/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Compute/locations/eastus/operations/1d21a2f6-5c64-408c-b37a-3479c234b7df?monitor=true&api-version=2015-05-01-previewAzure-AsyncOperation: https://management.azure.com/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Compute/locations/eastus/operations/1d21a2f6-5c64-408c-b37a-3479c234b7df?api-version=2015-05-01-preview

Generalize の Http Request

POST https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups  /ResourceGroup01/providers/Microsoft.Compute  /virtualMachines/testmachine01/generalize  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...

Generalize の Http Response

HTTP/1.1 200 OK

Capture の Http Request

POST https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups  /ResourceGroup01/providers/Microsoft.Compute  /virtualMachines/testmachine01/capture  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...Content-Type: application/json; charset=utf-8{  "vhdPrefix": "mycap",  "destinationContainerName": "myvhds",  "overwriteVhds": "true"}

Capture の Http Response

HTTP/1.1 202 AcceptedLocation: https://management.azure.com/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Compute/locations/eastus/operations/664d304e-0a62-45f0-8239-4298d763eb69?monitor=true&api-version=2015-05-01-previewAzure-AsyncOperation: https://management.azure.com/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Compute/locations/eastus/operations/664d304e-0a62-45f0-8239-4298d763eb69?api-version=2015-05-01-preview

なお、Capture など、Accepted Status (HTTP 202) が返っている操作は非同期に実行されています。(つまり、Capture の受け入れのみをおこなって HTTP Response を返し、バックグランドで Capture 操作が走ります。)
この進行状況を確認するには、上記の Azure-AsyncOperation ヘッダーに記載されている URI を使って状態を確認できます。(下記では、Capture が成功し、http://tsmatsuzteststorage01.blob.core.windows.net/system/Microsoft.Compute/Images/myvhds/mycap-osDisk.476ba657-8e4f-49af-9f50-5365de465543.vhd に image が保存されたことがわかります。)

HTTP Request

GET https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/providers  /Microsoft.Compute/locations/eastus/operations  /664d304e-0a62-45f0-8239-4298d763eb69  ?api-version=2015-05-01-previewAccept: application/jsonAuthorization: Bearer eyJ0eXA...

HTTP Response

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "operationId": "664d304e-0a62-45f0-8239-4298d763eb69",  "status": "Succeeded",  "startTime": "2015-09-09T05:04:13.0664488+00:00",  "endTime": "2015-09-09T05:04:15.8476583+00:00",  "properties": {    "output": {      "$schema": "http://schema.management.azure.com/schemas/2014-04-01-preview/VM_IP.json",      "contentVersion": "1.0.0.0",      "parameters": {        "vmName": {          "type": "string"        },        "vmSize": {          "type": "string",          "defaultValue": "Basic_A1"        },        "adminUserName": {          "type": "string"        },        "adminPassword": {          "type": "securestring"        },        "networkInterfaceId": {          "type": "string"        }      },      "resources": [        {          "apiVersion": "2015-05-01-preview",          "properties": {            "hardwareProfile": {              "vmSize": "[parameters('vmSize')]"            },            "storageProfile": {              "osDisk": {                "osType": "Windows",                "name": "mycap-osDisk.476ba657-8e4f-49af-9f50-5365de465543.vhd",                "createOption": "FromImage",                "image": {                  "uri": "http://tsmatsuzteststorage01.blob.core.windows.net/system/Microsoft.Compute/Images/myvhds/mycap-osDisk.476ba657-8e4f-49af-9f50-5365de465543.vhd"                },                "vhd": {                  "uri": "http://tsmatsuzteststorage01.blob.core.windows.net/vmcontainerc4f164f5-1f47-4394-91b0-9b1316da66db/osDisk.c4f164f5-1f47-4394-91b0-9b1316da66db.vhd"                },                "caching": "ReadWrite"              }            },            "osProfile": {              "computerName": "[parameters('vmName')]",              "adminUsername": "[parameters('adminUsername')]",              "adminPassword": "[parameters('adminPassword')]"            },            "networkProfile": {              "networkInterfaces": [                {                  "id": "[parameters('networkInterfaceId')]"                }              ]            },            "provisioningState": 0          },          "name": "[parameters('vmName')]",          "type": "Microsoft.Compute/virtualMachines",          "location": "eastus"        }      ]    }  }}

Azure Resource Explorer を使って各 Resource で実行可能な Action を確認できますので、是非参考にしてみてください。