Microsoft Azure REST API 使い方 まとめ

日山(@hiiyan0402)です。
Microsoft Azure サービス管理 REST API の使い方についてまとめました。


Microsoft Azure REST API 使い方 まとめ

目次

Microsoft Azure REST API とは

Microsoft Azure 管理ポータルサイトにて行っている操作を、自前のプログラムにてさせることが可能になります。
Microsoft Azureには管理ポータルサイト以外でも、クラウドサービスや仮想マシンなどのリソースに対して操作ができるように、”サービス管理 REST API”という REST API が公開されています。(リファレンスはこちら)
REST API は、例えば、管理ポータルで行う作業を自動化したいとき、などに使用することができます。
定期的に仮想マシン10台を起動/停止する必要がある場合、人力で決められた時間に仮想マシン10台に同じ操作をする、というのはちょっと面倒くさいし、ヒューマンエラーが発生する可能性がでてきます。そこで、定期的に仮想マシン起動/停止に相当する REST API を呼び出すプログラムを作成しておくことで、先ほどの作業を自動化することができます。
基本的には認証情報を付与して指定された URL を呼び出すだけで操作を行うことができますが、REST APIを呼び出すためのライブラリ(C#, Java, PHP, Node.jsなど)も公開されています。ライブラリを使うことにより、プログラムから簡単に REST API を呼び出せるようになり、オリジナルの Microsoft Azure 管理プログラムが作りやすくなります。
Build2014 で発表されたオートメーション機能(2014/04/12時点でプレビュー)を使えば、PowerShell により自動化することができますが、この REST API を使えば C# や Java など、PowerShellと比べるとユーザが多い言語にて、自動化プログラムを作成することができます。

目次に戻る

Microsoft Azure REST API で可能な操作一覧

クラウドサービスに関する操作

クラウドサービス一覧の取得 指定したサブスクリプションで使用可能なクラウドサービスを一覧表示する
クラウドサービス情報の取得 指定したクラウドサービスのプロパティを取得する
クラウドサービスの作成 新しいクラウドサービスを作成する
クラウドサービスの更新 クラウドサービスのラベルまたは説明を更新できます
クラウドサービスの削除 指定したクラウドサービスをサブスクリプションから削除する
クラウドサービス名の利用可否判定 指定したホステッド サービス名が使用できるかどうか、またはその名前が既に取得されているかどうかを確認する
デプロイメント情報の取得 デプロイの構成情報、ステータス、およびシステム プロパティを返する
デプロイメントの作成 新しいサービス パッケージをアップロードし、ステージング環境または運用環境に新しいデプロイを作成する
デプロイメントの更新 指定したパッケージと構成を使用して、デプロイのロール インスタンスの更新を開始する
デプロイメントの削除 指定したデプロイを削除する
デプロイメントステータスの更新 デプロイの実行ステータスの変更を開始する(Running/Suspended)
VIPスワップ サービスのステージング デプロイ環境と運用デプロイ環境間で仮想 IP スワップを開始する
配送パッケージの取得 デプロイのクラウドサービス パッケージを取得し、BLOB ストレージにパッケージ ファイルを保存する
ロールインスタンスの削除 クラウドサービスのデプロイから複数のロール インスタンスを削除する
ロールインスタンスの再起動 デプロイで実行されているロール インスタンスの再起動を要求する
ロールインスタンスの再イメージ化 Web ロールまたはワーカー ロールのインスタンスにオペレーティング システムを再インストールする
拡張機能一覧の取得 クラウドサービスに追加されたすべての拡張機能を一覧表示する
拡張機能情報の取得 クラウドサービスに追加された拡張機能の情報を取得する
拡張機能の追加 クラウドサービスに利用可能な拡張機能を追加する
拡張機能の削除 指定した拡張機能を削除する
利用可能な拡張機能一覧の取得 クラウドサービスに追加できる拡張機能を一覧表示する
拡張機能のバージョン一覧の取得 クラウドサービスに追加できる拡張機能のバージョンを一覧表示する
配置構成の変更 デプロイ構成に対する変更を開始する
更新またはアップグレードのロールバック 進行中の構成の更新を取り消して、デプロイを更新が開始される前の状態に戻する
インプレースアップグレードに関する操作 手動でのインプレース アップグレード中または構成変更中、次に処理するアップグレード ドメインを指定する

仮想マシンに関する操作

ロール情報の取得 指定した仮想マシンに関する情報を取得する
ロールの起動 指定した仮想マシンを起動する
ロールの停止 指定した仮想マシンをシャットダウンする
ロールの追加 仮想マシンのデプロイに仮想マシンを追加する
ロールの更新 指定した仮想マシンの構成を更新する
ロールの削除 指定した仮想マシンを削除する
ロールの取り込み 仮想マシンと関連付けられたオペレーティング システムの仮想ハード ディスク (VHD) のコピーを作成し、そのオペレーティング システムの VHD と同じ場所に VHD のコピーを保存して、イメージ リポジトリのイメージとしてそのコピーを登録する
ロールの再起動 指定した仮想マシンを再起動する
複数ロールの起動 複数の仮想マシンを起動する
複数ロールの停止 複数の仮想マシンをシャットダウンする
RDPファイルダウンロード 指定した仮想マシンからリモート デスクトップ プロトコル構成ファイルを取得する
仮想マシンデプロイの作成 指定した構成に基づいてデプロイを作成し、そのデプロイに仮想マシンを作成する
負荷分散入力エンドポイントの構成更新 デプロイ内のすべての仮想マシン上の指定した負荷分散入力エンドポイントの構成を更新する
リソース拡張機能一覧の取得 仮想マシンに追加できるリソース拡張機能を一覧表示する
リソース拡張機能のバージョン一覧の取得 仮想マシンに追加できるリソース拡張機能のバージョンを一覧表示する

Webサイトに関する操作

Web空間一覧の取得 サブスクリプションで利用可能なWeb空間の一覧を取得する
Web空間情報の取得 指定したWeb空間に関する情報を取得する
Web空間の証明書の取得 指定したWeb空間の証明書を取得する
Web空間の証明書の追加 指定したWeb空間へ証明書を追加する
Web空間の証明書の取得/削除 サムプリントにより指定したWeb空間の証明書を取得または削除する
Webサイト一覧の取得 指定したWeb空間のWebサイト一覧を取得する
Webサイト情報の取得 指定したWebサイトに関する情報を取得する
Webサイトの追加 Webサイトを作成する
Webサイトの更新 指定したWebサイトの構成を更新する
Webサイトの削除 指定したWebサイトを削除する
Webサイトの再起動 指定したWebサイトを再起動する
Webサイトの設定 指定したWebサイトの設定情報を取得または設定する
Webサイトモードの変更 指定したWebサイトのサイトモードを変更する
SSLの有効化/無効化 指定したWebサイトのSSLを有効化または無効化する
発行プロファイルの取得 指定したWebサイトの発行プロファイルを取得する
発行プロファイルのパスワード生成 指定したWebサイトの発行プロファイルのパスワードを生成する
メトリック情報の取得 (最新) 指定したWebサイトの最新メトリック情報を取得する
メトリック情報の取得 (統計) 指定したWebサイトのメトリック情報の統計情報を取得する
GITリポジトリの取得/追加 指定したWebサイトのGITリポジトリの取得または追加を行う
Server Farmの管理 指定した Server Farm を管理する

ストレージアカウントに関する操作

ストレージ アカウント一覧の取得 指定されたサブスクリプションで使用可能なストレージアカウントを一覧表示する
ストレージ アカウント情報の取得 指定されたストレージアカウントのシステムプロパティを返する
ストレージ アカウントの作成 WindowsAzureで新しいストレージアカウントを作成する
ストレージアカウントの更新 WindowsAzureのストレージアカウントのラベルと説明を更新し、ジオレプリケーションの状態を有効または無効にする
ストレージアカウントの削除 指定されたストレージアカウントをWindowsAzureから削除する
アクセスキーの取得 指定したストレージアカウントのプライマリアクセスキーとセカンダリアクセスキーを返する
アクセスキーの再生成 指定したストレージアカウントのプライマリアクセスキーまたはセカンダリアクセスキーを再生成する
アカウント名の利用可否判定 指定されたストレージアカウント名が使用できるかどうか、またはその名前が既に取得されているかどうかを確認する

SQLデータベースに関する操作

サーバーの一覧表示 サブスクリプションに関連付けられたサーバーの一覧を取得する
サーバーの作成 サブスクリプションIDにサーバーを作成する
サーバーの削除 サーバー上のすべてのデータベースを削除し、サーバー自体も削除する
サーバー管理者パスワードの設定 サーバーの管理者パスワードをリセットする
サブスクリプションの変更 (指定サーバー) 特定のサーバーを別のサブスクリプションへ移動する
サブスクリプションの変更 (全サーバー) すべてのサーバーを別のサブスクリプションへ移動する
サーバー イベント ログの取得 サーバーのイベントログを取得する
サービス レベル目標の一覧表示 サーバーのサービス目標を取得する
サービス レベル目標の取得 サーバーの特定のサービス目標を取得する
サービス目標ディメンション設定の一覧表示 サーバーのサービス目標ディメンション設定を取得する
サービス目標ディメンション設定の取得 サーバーのサービス目標ディメンション設定を取得する
クォータの一覧表示 サーバーのクォータを取得する
クォータの取得 サーバーのクォータを取得する
サブスクリプション メタデータの取得 サブスクリプションメタデータを取得する
データベースの一覧表示 指定したサーバーのデータベース一覧を取得する
データベースの取得 データベースの詳細を取得する
データベースの作成 サーバーにデータベースを作成する
データベースの更新 既存のデータベース情報を更新する
データベースの削除 サーバーからデータベースを削除する
データベース イベント ログの取得 データベースのイベントログを取得する

仮想ネットワークに関する操作

仮想ネットワーク一覧の取得 サブスクリプションに対して構成された仮想ネットワークを取得する
仮想ネットワーク情報の取得 ネットワーク構成ファイルを取得する
仮想ネットワークの更新 非同期的に仮想ネットワークを構成する
IPアドレス利用可否の判定 指定した仮想ネットワークで指定したIPアドレスが利用可能かを判定する

その他のサービスに関する操作

仮想ネットワークゲートウェイ、メディアサービス、トラフィックマネージャ、サブスクリプション、アフィニティ・グループ、アラート、自動スケーリング、Express Route、管理証明書、サービス証明書、場所、OS情報、に関する操作ができますが、多すぎるため割愛。

目次に戻る

Microsoft Azure REST API の利用方法

単純な REST API なので、MSDNリファレンスで記載されているURIに対して、指定されたHTTPメソッド(GET/PUT/POST/DELETE)でリクエストすることで、利用することができます。
リクエストには認証情報を付加する必要があります。あらかじめ、対象となるサブスクリプションに、管理ポータルで管理証明書の公開鍵(.cer)をアップロードしておき、対応する秘密鍵を認証情報としてリクエストに付加します。公開鍵のアップロード ~ 秘密鍵をリクエストに付加する方法はこちらをご参照ください。

サンプルコード (例:クラウドサービス一覧の取得)

using System;
using System.Net;
using System.Security.Cryptography.X509Certificates;
using System.Xml.Linq;

namespace MicrosoftAzureRestAPISample
{
    class Program
    {
        static void Main()
        {
            // 管理証明書の秘密鍵(.pfx)の準備
            const string encodedCertificate = "MIIKDAIBAzCCCcwGCSqGS...";
            var certificateBytes = Convert.FromBase64String(encodedCertificate);
            var certificate = new X509Certificate2(certificateBytes);

            // リクエストの作成
            const string subscriptionId = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
            const string baseUri = "https://management.core.windows.net/{0}/services/hostedservices";
            var uri = string.Format(baseUri, subscriptionId);
            var request = (HttpWebRequest)WebRequest.Create(uri);
            request.Method = "GET";
            request.Headers.Add("x-ms-version", "2014-02-01");
            request.ClientCertificates.Add(certificate);
            request.ContentType = "application/xml";

            // レスポンスを受信し、内容を出力する
            var response = (HttpWebResponse)request.GetResponse();
            var xml = XDocument.Load(response.GetResponseStream());
            Console.WriteLine(xml.ToString());
        }
    }
}

まず認証に使用する管理証明書の秘密鍵から、X509Certificate2 クラスを作成します。上記コードでは、Base64でエンコードされた秘密鍵から X509Certificate2 クラスを作成していますが、様々な方法があります。他の方法についてはこちらをご参照ください。
指定可能なバージョンは以下のサイトで確認可能です。
サービス管理のバージョン管理
http://msdn.microsoft.com/ja-jp/library/azure/gg592580.aspx

目次に戻る

Microsoft Azure REST API を利用するためのライブラリ

上記方法でも REST API を利用することができますが、マイクロソフトからより簡単に REST API を利用できるように、ライブラリが提供されています。
ライブラリは、C#, PHP, Node.js のものが用意されています。
C#用のライブラリとして Microsoft Azure Management Libraries が提供されています。
ライブラリはNugetにて提供されているため、Visual Studio のパッケージマネージャコンソールで以下のコマンドを実行することでインストールすることができます。

PM> Install-Package Microsoft.WindowsAzure.Management.Libraries

PHPとNode.jsのライブラリは以下をご参照ください。
Windows Azure SDK for PHP
https://github.com/WindowsAzure/azure-sdk-for-php
Windows Azure SDK for Node.js
https://github.com/WindowsAzure/azure-sdk-for-node

目次に戻る

Microsoft Azure Management Libraries の使い方 (基本編)

Microsoft Azure Management Libraries を使ってクラウドサービス一覧を表示します。
まずコンソールアプリケーションのプロジェクトを作成します。プロジェクト作成後に、パッケージマネージャーコンソールにて以下のコマンドを実行してライブラリをインストールします。

PM> Install-Package Microsoft.WindowsAzure.Management.Libraries

次に、Program.cs を以下の通りに実装します。これで完了です。

Program.cs

using System;
using System.Security.Cryptography.X509Certificates;
using System.Threading;
using Microsoft.WindowsAzure;

namespace MicrosoftAzureRestAPISample
{
    class Program
    {
        static void Main()
        {
            // REST APIアクセスで使用する認証情報を用意
            const string subscriptionId = "XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX";
            const string encodedCertificate = "MIIKDAIBAzCCCcwGCSqGS...";
            var certificateBytes = Convert.FromBase64String(encodedCertificate);
            var certificate = new X509Certificate2(certificateBytes);
            var credential = new CertificateCloudCredentials(subscriptionId, certificate);

            // REST APIにアクセスし、クラウドサービス一覧を取得
            var client = CloudContext.Clients.CreateComputeManagementClient(credential);
            var services = client.HostedServices.List();

            // クラウドサービス一覧を表示します
            foreach (var service in services)
            {
                Console.WriteLine(service.ServiceName);
            }
        }
    }
}

先ほどの例と同様に、サブスクリプションIDと管理証明書の秘密鍵として X509Certificate2 インスタンスを用意します。それらを使用して、CertificateCloudCredentials インスタンスを作成します。CloudContext クラスから各種サービスの操作用クライアントインスタンスを作成する際に使用します。今回はクラウドサービスの操作に関するクライアントを作成しましたが、同様の方法で各種サービスを操作するクライアントを作成することができます。クライアントが持つ操作クラスのメソッドを呼び出すことで、各種操作を行います。今回の場合、クラウドサービス一覧の取得を行い、出力しています。

目次に戻る

管理証明書による認証方法

必要な作業

REST API を利用するためには、操作対象となるサブスクリプションに管理証明書の公開鍵(.cer)をアップロードする必要があります。アップロードは管理ポータルで行うことができます。
hiyama20140413_1

自動で管理証明書をアップロード/ダウンロードする

Microsoft Azure サービスポータルで用意されている以下のサイトへアクセスすることで、管理証明書の公開鍵(.cer)のアップロードと、秘密鍵(.pfx)をBase64エンコードされた文字列を含む発行プロファイルのダウンロードを同時に行うことができます。
https://manage.windowsazure.com/publishsettings/
ただし、アクセスするだけで勝手に行われているため、頻繁にアクセスすると多数の管理証明書が登録されている状態になります。管理証明書の登録上限数は100個であるため、必要なときにだけアクセスすることをおすすめします。
hiyama20140413_2
アップロード/ダウンロード対象となるサブスクリプションは、管理ポータルにて選択中のディレクトリに所属するサブスクリプションになります。もし管理ポータルにアクセスしていない場合は、ディレクトリを選択することができます。
ダウンロードできる発行プロファイルの中身は以下の通りになっています。サブスクリプションID、サブスクリプション名、秘密鍵(.pfx)をBase64エンコードした文字列が含まれています。

[SubscriptionNames]-[PublishDay]-credentials.publishsettings

<?xml version="1.0" encoding="utf-8"?>
<PublishData>
  <PublishProfile
    SchemaVersion="2.0"
    PublishMethod="AzureServiceManagementAPI">
    <Subscription
      ServiceManagementUrl="https://management.core.windows.net"
      Id="901a993e-f620-XXXX-XXXX-XXXXXXXXXXXX"
      Name="SampleSubscription"
      ManagementCertificate="MIIKBAIBAzCCCcQGCSqGSIb3DQEHAaCCCbUEggmxMIe4..."/>
  </PublishProfile>
</PublishData>

秘密鍵(.pfx)をBase64エンコードした文字列から X509Certificate2 インスタンスを作成する方法は以下のとおりです。

const string encodedCertificate = "MIIKDAIBAzCCCcwGCSqGS...";
var certificateBytes = Convert.FromBase64String(encodedCertificate);
var certificate = new X509Certificate2(certificateBytes);

手動で管理証明書をアップロード/ダウンロードする

Visual Studio 開発者コマンドプロンプトの makecert コマンドで管理証明書を作成することができます。Visual Studio 2013 であれば、以下のパスあたりに “開発者コマンド プロンプト for VS2013” のショートカットがあるので起動します。念のため管理者権限で起動するといいかもしれないです。
> C:Program Files (x86)Microsoft Visual Studio 12.0Common7ToolsShortcuts
作業用フォルダに移動して、makecert コマンド実行します。コマンドを実行すると、秘密鍵のパスワードを入力するためのダイアログが表示されるので、任意のパスワードを入力してください。

> cd c:workspace
> makecert -sky exchange -r -n "CN=SampleManagementCertification" -pe -a sha1 -len 2048 "SampleManagementCertification.cer" -sv "SampleManagementCertification.pvk"

続いて、pfx形式の証明書を生成するために、pvk2pfx コマンドを実行します。

> pvk2pfx -pvk "SampleManagementCertification.pvk" -spc "SampleManagementCertification.cer" -pfx "SampleManagementCertification.pfx" -pi [さっき入力した秘密鍵のパスワード]

以上で作成した、管理証明書の公開鍵(.cer)を管理ポータルにてアップロードを行います。
hiyama20140413_3
作成した管理証明書の秘密鍵(.pfx)から X509Certificate2 インスタンスを作成する方法は以下のとおりです。

const string password = "inputed password";
var certificateBytes = File.ReadAllBytes("SampleManagementCertification.pfx");
var certificate = new X509Certificate2(certificateBytes, password);
目次に戻る

Microsoft Azure Management Libraries の使い方 (応用編)

具体的な使い方をコードで説明します。呼び出し元で CertificateCloudCredentials インスタンスが作成されていて、各メソッドに渡されるものとします。

指定したクラウドサービスの詳細情報の取得

private void GetHostedServiceInfo(CertificateCloudCredentials credentials,
                                  string serviceName)
{
    var client = CloudContext.Clients.CreateComputeManagementClient(credentials);
    var service = client.HostedServices.GetDetailed(serviceName);

    // クラウドサービスの情報を表示
    Console.WriteLine(service.ServiceName);
    Console.WriteLine(service.Properties.Status);

    foreach (var deployment in service.Deployments)
    {
        // デプロイメントスロット毎の情報を表示
        Console.WriteLine(deployment.DeploymentSlot);
        Console.WriteLine(deployment.Name);
        Console.WriteLine(deployment.Status);

        foreach (var role in deployment.Roles)
        {
            // ロールの情報を表示
            Console.WriteLine(role.RoleName);
            Console.WriteLine(role.RoleType);

            var instances = deployment.RoleInstances
                              .Where(instance => instance.RoleName == role.RoleName);
            foreach (var instance in instances)
            {
                // ロールインスタンスの情報を表示
                Console.WriteLine(instance.InstanceName);
                Console.WriteLine(instance.InstanceSize);
                Console.WriteLine(instance.InstanceStatus);
                Console.WriteLine(instance.PowerState);
                Console.WriteLine(instance.IPAddress);
            }
        }
    }
}

Webサイト一覧の取得

private void GetWebSites(CertificateCloudCredentials credentials)
{
    var client = CloudContext.Clients.CreateWebSiteManagementClient(credentials);

    // Web空間一覧を取得する
    var spaces = client.WebSpaces.List();
    foreach (var space in spaces)
    {
        // Web空間ごとにWebサイト一覧を取得する
        var parameters = new WebSiteListParameters();
        var sites = client.WebSpaces.ListWebSites(space.Name, parameters);
        foreach (var site in sites)
        {
            // Webサイト情報を表示する
            Console.WriteLine(site.Name);
            Console.WriteLine(site.State);
            Console.WriteLine(site.SiteMode);
            Console.WriteLine(site.Uri);
        }
    }
}

ストレージアカウント一覧の取得

private void GetStorageAccounts(CertificateCloudCredentials credentials)
{
    var client = CloudContext.Clients.CreateStorageManagementClient(credentials);
    var accounts = client.StorageAccounts.List();

    // ストレージアカウント名を一覧表示する
    foreach (var account in accounts)
    {
        Console.WriteLine(account.Name);
    }
}

指定したストレージアカウントのアクセスキーの取得

private void GetStorageAccountAccessKeys(CertificateCloudCredentials credentials,
                                            string accountName)
{
    var client = CloudContext.Clients.CreateStorageManagementClient(credentials);
    var keys = client.StorageAccounts.GetKeys(accountName);

    // プライマリキーとセカンダリキーを表示する
    Console.WriteLine(keys.PrimaryKey);
    Console.WriteLine(keys.SecondaryKey);
}

サブスクリプション情報の取得

private void GetSubscriptionInfo(CertificateCloudCredentials credentials)
{
    var client = CloudContext.Clients.CreateManagementClient(credentials);
    var subscription = client.Subscriptions.Get();

    // サブスクリプションに関する情報を表示する
    Console.WriteLine(subscription.SubscriptionID);
    Console.WriteLine(subscription.SubscriptionName);
    Console.WriteLine(subscription.SubscriptionStatus);
    Console.WriteLine(subscription.AccountAdminLiveEmailId);
    Console.WriteLine(subscription.CurrentCoreCount);
    Console.WriteLine(subscription.MaximumCoreCount);
}

サブスクリプション操作履歴一覧の取得

private void GetOperations(CertificateCloudCredentials credentials)
{
    var client = CloudContext.Clients.CreateManagementClient(credentials);
    var parameters = new SubscriptionListOperationsParameters
    {
        StartTime = DateTime.Now.AddDays(-7),   // 過去1週間分のログを取得
        EndTime = DateTime.Now,
    };
    var operations = client.Subscriptions.ListOperations(parameters);

    foreach (var operation in operations.SubscriptionOperations)
    {
        // 操作時刻、操作内容、操作者に関する情報を表示する
        Console.WriteLine(operation.OperationStartedTime.ToString());
        Console.WriteLine(operation.OperationCompletedTime.ToString());
        Console.WriteLine(operation.OperationName);
        Console.WriteLine(operation.OperationStatus);
        Console.WriteLine(operation.OperationCaller.ClientIPAddress);
        Console.WriteLine(operation.OperationCaller.UserEmailAddress);
        Console.WriteLine(operation.OperationCaller.UsedServiceManagementApi);
    }
}
目次に戻る

MSDNリファレンス

サービス管理 REST API リファレンス
http://msdn.microsoft.com/library/azure/ee460799.aspx
http://msdn.microsoft.com/en-us/library/azure/dn166981.aspx
ライブラリリファレンス
http://msdn.microsoft.com/ja-jp/library/azure/dn602775(v=azure.11).aspx
http://msdn.microsoft.com/ja-jp/library/azure/dn510414.aspx

目次に戻る
TechTarget

クラウドエンジニア  日山 雅之による記事「Microsoft Azure スマート解説」がTechTarget Japanにて好評連載中です (全7回)