API

ARMとAzure Insights API

Azure上のさまざまなサービスのメトリック情報をAPI経由で取得したい。そういうことであればAzure Service Management APIを使えばいいじゃないかという声が聞こえてきそうなところだが実は既にこのやり方は時代遅れとなっていることをご存じだろうか?
2014年5月ごろ?に登場したAzureの新しい考え方にResource、ResourceGroup、Azure Resource Managerというものがある。簡単な説明すると、Azure上のPaaSインスタンス、仮想マシンなどすべての管理可能な資源をリソース(Resource)とよばれる単位に細分化し、それらをグループ化したものがResourceGroup、そして全てのリソースはAzure Resource Manager(以下ARM)というもので管理可能になっている。そしてこのARMで管理可能な世界のリソース群に紐づくメトリックデータはAzure Insights APIで取得可能となっている。本記事ではさまざまなリソースの中でもWeb Appsに絞って、Azure Insights REST API (Metric)を使ってそのメトリックを取得する方法について紹介する。

ARM Explorerでどのメトリックが取得可能なのか確認する

ARM Explorer (https://resources.azure.com/) をご存じだろうか? これはその名の通りAzure上の全てのリソース(ご利用のサブスクリプションに紐づく全てのリソース)のエクスプローラーであり、これを使うことでこのARM管理下の世界のすべてのリソースをエクスプローラービューで閲覧することができる。このARM Explorerで閲覧可能な各リソースの情報の中にmetricdefinitionsというものがあって、これにはそのリソースに対して指定可能なメトリックの種類やその定義情報などが格納されている。リソースのメトリック取得をする際は、まずはARM Explorerで目的のリソースのmetricdefinitionsから指定可能なメトリックの種類を把握してからAPIリクエストを組み立てていただければと思う。ARM Explorerを使って本記事で取得対象としているWeb Apps(ここではサイト名yoichikademoを対象)のmetricdefinitionsを閲覧しているのが以下のスクリーンショットになる。


ARMExplorer

Azure Insights REST APIメトリック取得インターフェース

Azure Insights APIには次のような(1)メトリック定義一覧の取得と(2)対象リソースのメトリック情報取得の2つのインターフェースがある。当然ながらメトリックの取得には(2)のインターフェースを使用する。

APIの共通部分は下記の通り。Azure Insights APIへの全ての要求はAzure Active Directoryを使用して認証する必要があり、この認証により得られたトークンを各APIリクエストのAuthorizationヘッダに指定する必要がある。トークン取得の方法にはPowerShellを使用した方法とAzure管理ポータルを使用して認証する2つの方法がある。詳しくは「Azure インサイト要求を認証する」を参照ください。

実際のメトリクス取得APIでは$filterパラメータの付与が必要となる。$filterには主にメトリックの種類(name.value)、時間レンジ(startTime – endTime)、インターバール(timeGrain)の3種類の条件を指定する。

CpuTimeとMemoryWorkingSetメトリック指定例 (実際は1行にまとめる)

$filter=
  (name.value eq ‘CpuTime’ or name.value eq ‘MemoryWorkingSet’)
  and startTime eq ‘2015-08-01T15:00:00Z’ and endTime eq ‘2015-08-02T15:00:00Z’
  and timeGrain eq duration’PT1M’

$filterパラメータには実際はURL Encodeかけた文字列を渡す。メトリックのインターバル(timeGrain)は1分単位なら”PT1M”、5分単位なら”PT5M”、1時間単位ならば”PT1H”、1日単位ならば”PT1D”などを指定する。

サンプルコード

Azure Insightsのメトリック取得APIを使ってWeb Appのメトリックを取得するサンプルコードをGithubにアップした。同様のことを考えている人にとって少しでも参考になれば幸いである。

https://github.com/yokawasa/azure-samples/tree/master/GetAppServiceMetrics

このサンプルではCpuTime、MemoryWorkingSet、AverageResponseTimeの3つのメトリック情報を1時間ごとのインターバルで2015-08-01~2015-08-30の期間分取得するようになっている。この部分はハードコーディングしているので必要に応じてソースコード(Program.cs)を適宜変更いただければと思う。また利用者ごとの情報は設定ファイルApp.configで指定する。以下簡単にApp.configの設定内容を解説する。

App.config

<appSettings>
    <add key="subscriptionId" value="[your subscription Id]" />
    <add key="resourceGroup" value="[your resource group name]" />
    <add key="siteName" value="[site Name]" />
    <add key="tenantId" value="[you tenant ID]" />
    <add key="applicationId" value="[your application id]" />
    <add key="redirectUri" value='[redirect url]' />    
</appSettings>

LINKS

cUrlはUNIX/Linux系では有名なURLを使ったデータ送受信コマンドで手軽にREST系処理を実行するときにとても重宝している。そんなcUrlコマンドを使ってAzure Searchをお手軽に使ってみようというお話。

はじめに

まだの人はAzureポータルよりAzure Searchサービスを作成してください。「ポータルでの Azure Search サービスの作成」に優しく手順が書かれているのでご参考に。料金プランは無料と標準プランがあるがテストであれば無料プランで十分。まずはAPIキーまで取得ください。API実行のためにはAPIキーが必要。

cURLでSearch Service REST APIを実行

Search Service REST APIの中からいくつか代表的なAPIをピックアップしてcUrlでクエリを組み立ててみる。ここではインデックス新規作成、そこにいくつかドキュメントを追加、そしてドキュメントを検索する・・といった基本的なシナリオを実行する。ポイントとしてはcUrlの-Hオプションでヘッダ定義、-XオプションでHTTPメソッド指定、-dオプションでリクエストボディを指定する・・・といったところ。尚、下記サンプルでは現時点(2015-06-05)で最新のAPIバージョン2015-02-28-Previewを使用している。

1. インデックス新規作成

articlesという名前のブログ記事を格納するためのインデックスを作成する。インデックス生成にはCreate Index (Azure Search Service REST API)を利用する。

2. ドキュメントの追加

1で作成したインデックスにいくつかドキュメントをアップロードしてみる。データソースはMicrosoft Azure Japan BlogRSS。インデックスへのドキュメントのアップロードAPIはAdd, Update or Delete Documents (Azure Search Service REST APを参照ください。

3. ドキュメントの検索

追加されたドキュメントを実際に検索してみる。下記サンプルは”DocumentDB”キーワードで検索をして上位5つの結果を取得、レスポンスフィールドとしてitemidとtitleフィールドを指定している。ドキュメントの検索APIはSearch Documents (Azure Search Service REST API)を参照ください。

ただし上記の実行結果は次のように日本語マルチバイト文字がすべて”\uHHHH”のようなユニコードの16進表現でエンコードされている。さらに1行レスポンスであるため結果のJSON構造が非常に分かりづらく可読性のない状況となっている。

{"@odata.context":"https://yoichikaecdemo0.search.windows.net/indexes('articles')/$metadata#docs(itemid,title)","@odata.count":2,"value":[{"@search.score":1.1298637,"itemid":"1","title":"DocumentDB \u306e\u65b0\u3057\u3044\u30a4\u30f3\u30dd\u30fc\u30c8 \u30aa\u30d7\u30b7\u30e7\u30f3"},{"@search.score":1.058217,"itemid":"4","title":"DocumentDB SDK \u3067\u30d1\u30fc\u30c6\u30a3\u30b7\u30e7\u30f3\u5206\u5272\u3092\u30b5\u30dd\u30fc\u30c8"}]}

そこで上記の結果出力に対して(1)JSONを見やすくPretifyして、(2)16進数表現でエンコードされたUnicodeをデコードする2つの処理を加えたい。まずは(1)JSON Pretifyだが、Python2.6以上の環境であればで「python -mjson.tool」コマンドでJSONをPretify出力することができる。次に(2)16進数表現のデコードはStackOverflowで見つけたワンライナー「perl -Xpne ‘s/\\u([0-9a-fA-F]{4})/chr(hex($1))/eg’」を使用する。先のcUrlコマンドにこの2つの処理をパイプでつなげて加えてみたのが下記コード。

以下の実行結果のとおり無事JSON Pretify+デコードされた出力となった。

{
    "@odata.context": "https://yoichikaecdemo0.search.windows.net/indexes('articles')/$metadata#docs(itemid,title)",
    "@odata.count": 2,
    "value": [
        {
            "@search.score": 1.1298637,
            "itemid": "1",
            "title": "DocumentDB の新しいインポート オプション"
        },
        {
            "@search.score": 1.058217,
            "itemid": "4",
            "title": "DocumentDB SDK でパーティション分割をサポート"
        }
    ]
}

REST UIツール

今回cUrlコマンドでのお手軽にAPI実行を紹介したがREST系処理の実行ということであればFiddlerやPostmanのようなツールのほうがエンコード・デコード、JSON/XMLの整形表示など面倒な処理を自動でやってくれる分楽だったりする。特にPostmanはおすすめ。