こんにちは。

ISV 企業向けの Azure セミナーでデモした、ではなくて、デモする予定で時間切れとなった、Azure の Billing API (Preview) について、以下にコードを含めて解説します。

Azure には、ARM ベースの API の 1 つとして、ここで紹介する Azure Resource Usage API と Azure Resource RateCard API が提供されており、これらの API と Azure Resource Manager で提供されている Tag を使用することで、例えば、「お客様ごと」、「開発環境と運用環境」といった細かな集計処理 (利用状況の取得) が可能です。

Azure 上でサービスを提供している企業や、Azure を使った CSP (Cloud Solution Provider) など、是非活用してみてください。(Cloudyn のような高度な Cost Operation 機能も提供できます。)

準備 : 権限設定 (RBAC) と認証 (Authentication)

REST API を呼び出すための事前の権限設定と認証 (Authentication) の処理は、「Azure Resource の REST API による管理」で解説した方法と同様です。
ここでは手順の説明を省略しますが、ARM ベースの REST API に慣れていない方は「Azure Resource の REST API による管理」で解説した手順に従って、RBAC を使った User への Role の付与、Azure AD への Application の登録、OAuth Flow の実装 (プログラミング) による access token の取得をおこないます。(指定する resource も「Azure Resource の REST API による管理」と同じ内容で OK です。)

なお、今回は、RBAC を使って、使用するユーザーに対して Subscription の Reader ロールを付与しておいてください。

Azure Resource Usage API

Azure Resource Usage API は、Subscription における Resource の利用量を取得する API です。
この API 自身は Billing (Cost) の情報を返しませんが、後述する Azure Resource RateCard API が返すメタデータを使って料金計算が可能です。

Usage API の最も基本的な HTTP Request は下記の通りです。(各 query string については、このあと解説します。)
Authorization Header には、上記で取得した access token を設定します。

GET https://management.azure.com/subscriptions  /{subscription-id}/providers  /Microsoft.Commerce/UsageAggregates  ?api-version={api-version}  &reportedStartTime={dateTimeOffset-value}  &reportedEndTime={dateTimeOffset-value}  &aggregationGranularity={granularity-value}  &showDetails={showdetail-boolean-value}Accept: application/jsonAuthorization: Bearer {access token}

上記の Subscription id は Azure Portal などから確認できます。

また、上記の reportedStartTime と reportedEndTime には、取得する Usage Report の開始日時と終了日時を GMT で指定します。
aggregationGranularity には Daily (日ごと) か Hourly (時間ごと) を指定します。

例えば、下記は、2015-08-30T00:00:00+00:00 から 2015-09-30T00:00:00+00:00 の、Daily の Usage (Consumption) Report を取得する HTTP Request です。

GET https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/providers  /Microsoft.Commerce/UsageAggregates  ?api-version=2015-06-01-preview  &reportedStartTime=2015-08-30T00%3a00%3a00%2b00%3a00  &reportedEndTime=2015-09-30T00%3a00%3a00%2b00%3a00  &aggregationGranularity=Daily  &showDetails=trueAccept: application/jsonAuthorization: Bearer eyJ0eXAiOi...

この HTTP Response は、下記の通りです。
quantity が実際の利用量 (前述の通り、金額ではありません) です。金額関連の情報については、このあとの Azure Resource RateCard API で解説します。

HTTP/1.1 200 OKContent-Type: application/json{  "value": [    {      "id": "/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Commerce/UsageAggregates/Daily_BRSDT_20150830_0000",      "name": "Daily_BRSDT_20150830_0000",      "type": "Microsoft.Commerce/UsageAggregate",      "properties": {        "subscriptionId": "af254894-bed5-44c5-9f6b-288427de57c1",        "usageStartTime": "2015-08-26T00:00:00+00:00",        "usageEndTime": "2015-08-27T00:00:00+00:00",        "meterName": "Data Transfer Out (GB)",        "meterRegion": "Zone 2",        "meterCategory": "Networking",        "unit": "GB",        "meterId": "fe167397-a38d-43c3-9bb3-8e2907e56a41",        "infoFields": {          "meteredRegion": "Japan East",          "meteredService": "Azure App Service",          "meteredServiceType": "External",          "project": "addintest01"        },        "quantity": 0.000458      }    },    {      "id": "/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/providers/Microsoft.Commerce/UsageAggregates/Daily_BRSDT_20150830_0000",      "name": "Daily_BRSDT_20150830_0000",      "type": "Microsoft.Commerce/UsageAggregate",      "properties": {        "subscriptionId": "af254894-bed5-44c5-9f6b-288427de57c1",        "usageStartTime": "2015-09-09T00:00:00+00:00",        "usageEndTime": "2015-09-10T00:00:00+00:00",        "meterName": "Compute Hours",        "meterRegion": "US East",        "meterCategory": "Virtual Machines",        "meterSubCategory": "BASIC.A1 VM (Windows)",        "unit": "Hours",        "instanceData":          "{"Microsoft.Resources":            {"resourceUri":"/subscriptions/af254894-bed5-44c5-9f6b-288427de57c1/resourceGroups/ResourceGroup01/providers/Microsoft.Compute/virtualMachines/testmachine01",             "location":"eastus",             "tags":{"Env":"Dev"},             "additionalInfo":{"UsageType":"ComputeHR"}}}",        "meterId": "99e96e8b-46a6-4666-b4d2-c55778d92367",        "infoFields": {        },        "quantity": 0.466676      }    },    . . .  ]}

Tag を使った高度な集計

上記の HTTP Response を見てください。1 番目の要素には infoFields、2 番目の要素には instanceData が設定されています。v1 resource (Classic) の場合は付帯情報として infoFields、v2 resource (Resource Manager) の場合は付帯情報として instanceData が使用されます。
そして、実は、ここに有益な情報が含まれています。

新しい ARM (Azure Resource Manager) ベースの Resource では Tag と呼ばれる Key-Value ペアのデータを各 Resource ごとに最大 15 個まで設定できます。例えば、Tag を使って、顧客ごとに ID を付与したり、開発環境 / テスト環境 / 運用環境などの区分情報を付与できます。

この Tag の設定方法は、「Azure Resource Manager の template の How-to」で解説した template を使って設定もできますし、Azure Portal の UI を使って後から設定することも可能です。(Portal 上では、特定の Tag を持つ Resource の一覧なども表示可能です。)

Resource Manager Template で設定する場合

{  "name": "testwin01",  "type": "Microsoft.Compute/virtualMachines",  "location": "West US",  "apiVersion": "2015-05-01-preview",  "dependsOn": [. . .  ],  "tags": {"displayName": "testwin01","Env": "Test"  },  . . .}

Azure Portal で設定する場合

上記の HTTP Response の instanceData を見てください。
Escape された文字列で、

“tags”:{“Env”:”Dev”}

と記載されていますが、これが、この Resource の Tag の情報です。

つまり、上述の Azure Resource Usage API を使って Tag の情報が返されるため、例えば、利用顧客ごとの金額の算出など、この Tag を使ったさまざまな集計が可能です。

補足 : Azure Account Portal (Azure Account Center) から使用量 (Usage) の Report (csv) をダウンロードしても、Tag (タグ) の内容が取得できます。ただし、ダウンロードの際に、version 2 の Report を選択してください。

Azure Resource RateCard API

Azure Resource RateCard API は、その Subscription で利用可能な Resource の Billing のメタ情報 (単価など) を取得します。
前述の通り、Azure Resource Usage API 自身は Billing (Cost) の情報を返しませんが、ここで紹介する Azure Resource RateCard API を組み合わせることで料金計算 (推定値) が可能になります。

RateCard API の HTTP Request は下記の通りです。(空白等は URL Encode してください。)

GET https://management.azure.com/subscriptions  /{subscription-id}/providers  /Microsoft.Commerce/RateCard  ?api-version={api-version}  &$filter=OfferDurableId eq '{OfferDurableId}' and Currency eq '{Currency}' and Locale eq '{Locale}' and RegionInfo eq '{RegionInfo}'Accept: application/jsonAuthorization: Bearer {access token}

上記の $filter は OData のシンタックスで、以下を意味しています。(この 4 つの parameter は必ず指定する必要があります。)

(OfferDurableId = ‘{OfferDurableId}’) and (Currency = ‘{Currency}’) and (Locale = ‘{Locale}’) and (RegionInfo = ‘{RegionInfo}’)

補足 : 現在 (2015/09 の Preview 段階では)、$filter の query option として「eq」と「and」のみがサポートされています。(or 等は使用できません。)

OfferDurableId は「MS-AZR-xxxxx」の形式の文字列で、xxxxx には下記の Offer Number を設定します。例えば、Pay-As-You-Go (従量課金) の契約の場合は MS-AZR-0003P、Free Trial (無料試用版) の契約の場合は MS-AZR-0044P となります。

Microsoft Azure Offer Details

https://azure.microsoft.com/en-us/support/legal/offer-details/

例えば、下記は、従量課金 (Pay-As-You-Go) 契約における日本での料金情報を、日本円 (JPY) をベースとして要求する HTTP Request です。

GET https://management.azure.com/subscriptions  /af254894-bed5-44c5-9f6b-288427de57c1/providers  /Microsoft.Commerce/RateCard  ?api-version=2015-06-01-preview  &$filter=OfferDurableId%20eq%20%27MS-AZR-0003p%27  %20and%20Currency%20eq%20%27JPY%27  %20and%20Locale%20eq%20%27ja-JP%27  %20and%20RegionInfo%20eq%20%27JP%27Accept: application/jsonAuthorization: Bearer eyJ0eXAiOi...

この HTTP Response は下記のようになります。(途中は省略します。)

HTTP/1.1 200 OKContent-Type: application/json; charset=utf-8{  "OfferTerms": [],  "Meters": [    {      "MeterId": "3c5324ad-eb8c-44c6-af9a-6741ae75fc90",      "MeterName": "500 Mbps での Data Transfer - 送信 (GB)",      "MeterCategory": "ネットワーク",      "MeterSubCategory": "ExpressRoute (IXP)",      "Unit": "GB",      "MeterTags": [],      "MeterRegion": "ゾーン 3",      "MeterRates": {        "0": 10.2      },      "EffectiveDate": "2014-08-01T00:00:00Z",      "IncludedQuantity": 2048.0    },    {      "MeterId": "99e96e8b-46a6-4666-b4d2-c55778d92367",      "MeterName": "Compute 時間",      "MeterCategory": "Virtual Machines",      "MeterSubCategory": "BASIC.A1 VM (Windows)",      "Unit": "時間",      "MeterTags": [],      "MeterRegion": "米国東部",      "MeterRates": {        "0": 7.548      },      "EffectiveDate": "2014-02-11T00:00:00Z",      "IncludedQuantity": 0.0    },    . . .  ],  "Currency": "JPY",  "Locale": "ja-JP",  "IsTaxIncluded": false}

上記の 2 番目の MeterId を見ると、前述の Azure Resource Usage API の 2 番目の MeterId と一致しています。
つまり、前述の Azure Resource Usage API の 2 番目の要素は、Azure Virtual Machine の Basic A1 (Windows) に関する使用量で、この 1 時間あたりの単価は約 7.548 円であることを示しています。
Application では、このように RateCard の内容を Usage (Consumption) の情報と組み合わせることで、現在の推定の利用料金の合計や、前述した Tag 別の算出など、細やかな料金計算を自動化 (プログラミング) できます。

なお、Azure では、よく使用量に応じて単価が安くなるケースがありますが、このような場合は下記の通り MeterRates が複数返されます。

{  "MeterId": "4d555982-7f9a-4884-a128-780030263ab5",  "MeterName": "Premium CDN Data Transfer (GB)",  "MeterCategory": "CDN",  "MeterSubCategory": "",  "Unit": "GB",  "MeterTags": [],  "MeterRegion": "ゾーン 1",  "MeterRates": {    "0": 8.670,    "10240": 7.650,    "51200": 6.630,    "153600": 5.610,    "512000": 5.10,    "1048576": 4.590,    "5242880": 4.590  },  . . .}

※参考情報

ScottGu’s Blog : New Azure Billing APIs Available

http://weblogs.asp.net/scottgu/new-azure-billing-apis-available