Resource Manager REST APIResource Manager REST APIs

Azure Resource Manager、デプロイ済みのテンプレート、構成済みのストレージ アカウントを呼び出す裏では、必ず Azure Resource Manager の RESTful API が 1 回以上呼び出されます。Behind every call to Azure Resource Manager, behind every deployed template, behind every configured storage account there are one or more calls to the Azure Resource Manager's RESTful API. このトピックでは、これらの API と、SDK を一切使わずにこれらの API を呼び出す方法について説明します。This topic is devoted to those APIs and how you can call them without using any SDK at all. この方法は、Azure への要求を完全に制御したい場合や、優先言語の SDK が利用できないか、必要な操作がその SDK でサポートされていない場合に、役に立ちます。This approach is useful if you want full control of requests to Azure, or if the SDK for your preferred language is not available or doesn't support the operations you need.

この記事では Azure で公開されているすべての API については説明しませんが、一部の操作を接続例として取り上げます。This article does not go through every API that is exposed in Azure, but rather uses some operations as examples of how you connect to them. 基本を理解できたら、Azure Resource Manager REST API リファレンスで残りの API の使い方を調べることができます。After you understand the basics, you can read the Azure Resource Manager REST API Reference to find detailed information on how to use the rest of the APIs.

認証Authentication

Resource Manager の認証は、Azure Active Directory (AD) によって処理されます。Authentication for Resource Manager is handled by Azure Active Directory (AD). 任意の API に接続するには、最初に Azure AD で認証を行って認証トークンを受信する必要があります。この認証トークンは、すべての要求に対して渡すことができます。To connect to any API, you first need to authenticate with Azure AD to receive an authentication token that you can pass on to every request. ここでは REST API の直接的で純粋な呼び出しについて説明するため、ユーザー名やパスワードの入力を求める画面が表示される認証を望んでいないと想定しています。As we are describing a pure call directly to the REST APIs, we assume that you don't want to authenticate by being prompted for a username and password. また、2 要素認証のメカニズムを使用していないということも想定しています。We also assume you are not using two factor authentication mechanisms. したがって、Azure AD アプリケーションと、ログインに使用するサービス プリンシパルを作成します。Therefore, we create what is called an Azure AD Application and a service principal that are used to log in. ただし、Azure AD は複数の認証手順をサポートしており、そのどれを使っても、後続の API 要求に必要な認証トークンを取得できることに注意してください。But remember that Azure AD support several authentication procedures and all of them could be used to retrieve that authentication token that we need for subsequent API requests. 詳しい手順については、Azure AD アプリケーションとサービス プリンシパルの作成に関する記事をご覧ください。Follow Create Azure AD Application and Service Principal for step by step instructions.

アクセス トークンの生成Generating an Access Token

Azure AD に対する認証は、login.microsoftonline.com にある Azure AD を呼び出すことで行われます。認証のためには次の情報が必要です。Authentication against Azure AD is done by calling out to Azure AD, located at login.microsoftonline.com. To authenticate, you need to have the following information:

  • Azure AD テナント ID (ログインに使用している Azure AD の名前。会社名と同じである場合が多いですが、必ずしもそうとは限りません)Azure AD Tenant ID (the name of that Azure AD you are using to log in, often the same as your company but not necessary)
  • アプリケーション ID (Azure AD アプリケーションの作成中に取得したもの)Application ID (taken during the Azure AD application creation step)
  • パスワード (Azure AD アプリケーションの作成中に選択したもの)Password (that you selected while creating the Azure AD Application)

次の HTTP 要求で、"Azure AD Tenant ID"、"Application ID"、"Password" を適切な値に置き換えてください。In the following HTTP request, make sure to replace "Azure AD Tenant ID", "Application ID" and "Password" with the correct values.

一般的な HTTP 要求:Generic HTTP Request:

POST /<Azure AD Tenant ID>/oauth2/token?api-version=1.0 HTTP/1.1 HTTP/1.1
Host: login.microsoftonline.com
Cache-Control: no-cache
Content-Type: application/x-www-form-urlencoded

grant_type=client_credentials&resource=https%3A%2F%2Fmanagement.core.windows.net%2F&client_id=<Application ID>&client_secret=<Password>

この要求により、(認証に成功した場合は) 次のような応答が返されます。... will (if authentication succeeds) result in a response similar to the following response:

{
  "token_type": "Bearer",
  "expires_in": "3600",
  "expires_on": "1448199959",
  "not_before": "1448196059",
  "resource": "https://management.core.windows.net/",
  "access_token": "eyJ0eXAiOiJKV1QiLCJhb...86U3JI_0InPUk_lZqWvKiEWsayA"
}

(読みやすくするために、上記の応答の access_token は短縮されています)(The access_token in the preceding response have been shortened to increase readability)

Bash を使ったアクセス トークンの生成:Generating access token using Bash:

curl -X POST -H "Content-Type: application/x-www-form-urlencoded" -d "grant_type=client_credentials&resource=https://management.core.windows.net/&client_id=<application id>&client_secret=<password you selected for authentication>" https://login.microsoftonline.com/<Azure AD Tenant ID>/oauth2/token?api-version=1.0

PowerShell を使ったアクセス トークンの生成:Generating access token using PowerShell:

Invoke-RestMethod -Uri https://login.microsoftonline.com/<Azure AD Tenant ID>/oauth2/token?api-version=1.0 -Method Post
 -Body @{"grant_type" = "client_credentials"; "resource" = "https://management.core.windows.net/"; "client_id" = "<application id>"; "client_secret" = "<password you selected for authentication>" }

応答には、アクセス トークン、そのトークンの有効期限に関する情報、そのトークンを使えるリソースに関する情報が含まれます。The response contains an access token, information about how long that token is valid, and information about what resource you can use that token for. 前の HTTP 呼び出しで受け取ったアクセス トークンを、すべての要求に対して、Resource Manager API に渡す必要があります。The access token you received in the previous HTTP call must be passed in for all request to the Resource Manager API. 値 "Bearer YOUR_ACCESS_TOKEN" で "Authorization" というヘッダー値として渡します。You pass it as a header value named "Authorization" with the value "Bearer YOUR_ACCESS_TOKEN". "Bearer" とアクセス トークンの間のスペースに注意してください。Notice the space between "Bearer" and your access token.

上記の HTTP の結果からわかるとおり、トークンは特定の期間、有効です。その期間中は、トークンをキャッシュし、同じトークンを再利用する必要があります。As you can see from the above HTTP Result, the token is valid for a specific period of time during which you should cache and reuse that same token. API 呼び出しごとに Azure AD に対して認証を行うことができたとしても、著しく非効率です。Even if it is possible to authenticate against Azure AD for each API call, it would be highly inefficient.

Resource Manager REST API の呼び出しCalling Resource Manager REST APIs

このトピックでは、一部の API のみを使用して、REST 操作の基本的な使用方法を説明します。This topic only uses a few APIs to explain the basic usage of the REST operations. すべての操作の詳細については、Azure リソース マネージャー REST API に関する記事を参照してください。For information about all the operations, see Azure Resource Manager REST APIs.

すべてのサブスクリプションの一覧表示List all subscriptions

実行できる最も簡単な操作の 1 つに、アクセスできる利用可能なサブスクリプションの一覧表示があります。One of the simplest operations you can do is to list the available subscriptions that you can access. 次の要求には、アクセス トークンをヘッダーとして渡す方法が示されています。In the following request, you see how the access token is passed in as a header:

(YOUR_ACCESS_TOKEN を実際のアクセス トークンに置き換えてください)(Replace YOUR_ACCESS_TOKEN with your actual Access Token.)

GET /subscriptions?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

この要求の結果、このサービス プリンシパルでアクセスできるサブスクリプションの一覧が返されます。... and as a result, you get a list of subscriptions that this service principal is allowed to access

(サブスクリプション ID は読みやすいように短縮されています)(Subscription IDs have been shortened for readability)

{
  "value": [
    {
      "id": "/subscriptions/3a8555...555995",
      "subscriptionId": "3a8555...555995",
      "displayName": "Azure Subscription",
      "state": "Enabled",
      "subscriptionPolicies": {
        "locationPlacementId": "Internal_2014-09-01",
        "quotaId": "Internal_2014-09-01"
      }
    }
  ]
}

特定のサブスクリプションに含まれる全リソース グループの一覧表示List all resource groups in a specific subscription

Resource Manager API で使用できるリソースは、いずれもリソース グループの入れ子になっています。All resources available with the Resource Manager APIs are nested inside a resource group. 次の HTTP GET 要求を使って、サブスクリプションに含まれる既存のリソース グループを Resource Manager に対して照会します。You can query Resource Manager for existing resource groups in your subscription using the following HTTP GET request. ここではどのような形でサブスクリプション ID が URL の一部として渡されているか、注目してください。Notice how the subscription ID is passed in as part of the URL this time.

(YOUR_ACCESS_TOKEN と SUBSCRIPTION_ID を実際のアクセス トークンとサブスクリプション ID に置き換えてください)(Replace YOUR_ACCESS_TOKEN and SUBSCRIPTION_ID with your actual access token and subscription ID)

GET /subscriptions/SUBSCRIPTION_ID/resourcegroups?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

返される応答は、定義済みのリソース グループの有無によって変わります。定義済みのリソース グループがある場合は、その数によって変わります。The response you get depends on whether you have any resource groups defined and if so, how many.

(サブスクリプション ID は読みやすいように短縮されています)(Subscription IDs have been shortened for readability)

{
    "value": [
        {
            "id": "/subscriptions/3a8555...555995/resourceGroups/myfirstresourcegroup",
            "name": "myfirstresourcegroup",
            "location": "eastus",
            "properties": {
                "provisioningState": "Succeeded"
            }
        },
        {
            "id": "/subscriptions/3a8555...555995/resourceGroups/mysecondresourcegroup",
            "name": "mysecondresourcegroup",
            "location": "northeurope",
            "tags": {
                "tagname1": "My first tag"
            },
            "properties": {
                "provisioningState": "Succeeded"
            }
        }
    ]
}

リソース グループの作成Create a resource group

これまで、情報を得るためだけに Resource Manager API をクエリしていました。So far, we've only been querying the Resource Manager APIs for information. ここで、いくつかリソースを作成します。まず、最も簡単なリソース グループから始めましょう。It's time we create some resources, and let's start by the simplest of them all, a resource group. 次の HTTP 要求は指定したリージョン/場所にリソース グループを作成し、それにタグを追加します。The following HTTP request creates a resource group in a region/location of your choice, and adds a tag to it.

(YOUR_ACCESS_TOKEN、SUBSCRIPTION_ID、RESOURCE_GROUP_NAME を実際のアクセス トークン、サブスクリプション ID、作成するリソース グループの名前に置き換えてください)(Replace YOUR_ACCESS_TOKEN, SUBSCRIPTION_ID, RESOURCE_GROUP_NAME with your actual Access Token, Subscription ID and name of the Resource Group you want to create)

PUT /subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "location": "northeurope",
  "tags": {
    "tagname1": "test-tag"
  }
}

成功した場合、次のような応答を取得します。If successful, you get a response that is similar to the following response:

{
  "id": "/subscriptions/3a8555...555995/resourceGroups/RESOURCE_GROUP_NAME",
  "name": "RESOURCE_GROUP_NAME",
  "location": "northeurope",
  "tags": {
    "tagname1": "test-tag"
  },
  "properties": {
    "provisioningState": "Succeeded"
  }
}

これでリソース グループを Azure で正常に作成できました。You've successfully created a resource group in Azure. お疲れさまでした。Congratulations!

Resource Manager テンプレートを使ってリソース グループにリソースをデプロイするDeploy resources to a resource group using a Resource Manager Template

Resource Manager では、テンプレートを使ってリソースをデプロイできます。With Resource Manager, you can deploy your resources using templates. テンプレートには、いくつかのリソースとその依存関係が定義されます。A template defines several resources and their dependencies. このセクションは Resource Manager テンプレートに精通している読者を想定しているため、API 呼び出しによりそのデプロイを始める方法のみを紹介します。For this section, we assume you are familiar with Resource Manager templates, and we just show you how to make the API call to start deployment. テンプレートの作成の詳細については、「Azure リソース マネージャーのテンプレートの作成」を参照してください。For more information about constructing templates, see Authoring Azure Resource Manager templates.

テンプレートのデプロイは、他の API を呼び出す方法とそれほど違いはありません。Deployment of a template doesn't differ much to how you call other APIs. 重要な点は、テンプレートのデプロイにはかなりの時間がかかる可能性があるという点です。One important aspect is that deployment of a template can take quite a long time. API の呼び出しは単に返るだけなので、デプロイが完了したタイミングを把握するためには、開発者がデプロイの状態を照会する必要があります。The API call just returns, and it's up to you as developer to query for status of the deployment to find out when the deployment is done. 詳細については、「Track asynchronous Azure operations (非同期の Azure 操作の追跡)」を参照してください。For more information, see Track asynchronous Azure operations.

この例では、GitHub で一般公開されているテンプレートを使います。For this example, we use a publicly exposed template available on GitHub. ここで使用するテンプレートは、Linux VM を米国西部のリージョンに配置します。The template we use deploys a Linux VM to the West US region. この例では GitHub などのパブリック リポジトリで公開されているテンプレートを使用しますが、代わりに要求の一部で完全なテンプレートを渡すこともできます。Even though this example uses a template available in a public repository like GitHub, you can instead pass the full template as part of the request. デプロイするテンプレート内で使用される要求で、パラメーター値を指定することに注意してください。Note that we provide parameter values in the request that are used inside the deployed template.

(SUBSCRIPTION_ID、RESOURCE_GROUP_NAME、DEPLOYMENT_NAME、YOUR_ACCESS_TOKEN、GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME、ADMIN_USER_NAME、ADMIN_PASSWORD、DNS_NAME_FOR_PUBLIC_IP を独自の要求に適した値に置き換えてください)(Replace SUBSCRIPTION_ID, RESOURCE_GROUP_NAME, DEPLOYMENT_NAME, YOUR_ACCESS_TOKEN, GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME, ADMIN_USER_NAME, ADMIN_PASSWORD and DNS_NAME_FOR_PUBLIC_IP to values appropriate for your request)

PUT /subscriptions/SUBSCRIPTION_ID/resourcegroups/RESOURCE_GROUP_NAME/providers/microsoft.resources/deployments/DEPLOYMENT_NAME?api-version=2015-01-01 HTTP/1.1
Host: management.azure.com
Authorization: Bearer YOUR_ACCESS_TOKEN
Content-Type: application/json

{
  "properties": {
    "templateLink": {
      "uri": "https://raw.githubusercontent.com/Azure/azure-quickstart-templates/master/101-simple-linux-vm/azuredeploy.json",
      "contentVersion": "1.0.0.0",
    },
    "mode": "Incremental",
    "parameters": {
        "newStorageAccountName": {
          "value": "GLOBALY_UNIQUE_STORAGE_ACCOUNT_NAME"
        },
        "adminUsername": {
          "value": "ADMIN_USER_NAME"
        },
        "adminPassword": {
          "value": "ADMIN_PASSWORD"
        },
        "dnsNameForPublicIP": {
          "value": "DNS_NAME_FOR_PUBLIC_IP"
        },
        "ubuntuOSVersion": {
          "value": "15.04"
        }
    }
  }
}

このドキュメントを読みやすくするために、この要求に対する長い JSON の応答は省略されています。The long JSON response for this request has been omitted to improve readability of this documentation. 応答には、先ほど作成したテンプレート化されたデプロイに関する情報が含まれます。The response contains information about the templated deployment that you created.

次のステップNext steps