Azure Monitor Log Analytics API にアクセスする

[アーティクル]
10/23/2023

Azure Monitor Log Analytics エンドポイント https://api.loganalytics.azure.com を使用して、ワークスペースにクエリ要求を送信できます。エンドポイントにアクセスするには、Microsoft Entra ID を使って認証を行う必要があります。

Note

api.loganalytics.io エンドポイントは api.loganalytics.azure.com に置き換えられています。 api.loganalytics.io エンドポイントが今後も引き続きサポートされます。

デモ API キーを使用した認証

Microsoft Entra 認証なしで API をすばやく探索するには、API キー認証がサポートされている、サンプルデータを含むデモワークスペースを使用します。

サンプルワークスペースに対して認証を行ってクエリを実行するには、{workspace-id} として DEMO_WORKSPACE を使用し、API キー DEMO_KEY を渡します。

アプリケーション ID または API キーが正しくない場合は、API サービスによって 403 (Forbidden) エラーが返されます。

API キー DEMO_KEY は、ヘッダー、URL、または基本認証のどれを使用するかに応じて、3 つの異なる方法で渡すことができます。

カスタムヘッダー: カスタムヘッダー X-Api-Key で API キーを提供します。
クエリパラメーター: URL パラメーター api_key で API キーを提供します。
基本認証: ユーザー名またはパスワードとして API キーを提供します。両方を指定する場合、API キーはユーザー名に含まれている必要があります。

この例では、ヘッダーでワークスペース ID と API キーを使用しています。

    POST https://api.loganalytics.azure.com/v1/workspaces/DEMO_WORKSPACE/query
    X-Api-Key: DEMO_KEY
    Content-Type: application/json
    
    {
        "query": "AzureActivity | summarize count() by Category"
    }

パブリック API エンドポイント

パブリック API エンドポイントは、次のようになります。

    https://api.loganalytics.azure.com/{api-version}/workspaces/{workspaceId}

ここで、

api-version: API のバージョン。現在のバージョンは "v1" です。
workspaceId: ワークスペース ID。

クエリは、要求本文で渡されます。

次に例を示します。

   https://api.loganalytics.azure.com/v1/workspaces/1234abcd-def89-765a-9abc-def1234abcde
   
   Body:
   {
       "query": "Usage"
   }

認証の設定

API にアクセスするには、クライアントアプリを Microsoft Entra ID に登録して、トークンを要求します。

アプリを Microsoft Entra ID に登録します。
アプリの概要ページで、[API のアクセス許可] を選択します。
[アクセス許可の追加] を選択します。
[組織が使用している API] タブで Log Analytics を検索し、一覧から [Log Analytics API] を選択します。
[委任されたアクセス許可] を選択します。
[Data.Read] チェックボックスをオンにします。
[アクセス許可の追加] を選択します.

アプリが登録され、API を使用するアクセス許可が与えられたので、Log Analytics ワークスペースへのアクセス権をアプリに付与します。

Log Analytics ワークスペースの [概要] ページで、[アクセス制御 (IAM)] を選択します。
[ロールの割り当ての追加] を選択します。
[閲覧者] ロールを選択してから、[メンバー] を選択します。
[メンバー] タブで、[メンバーの選択] を選択します。
[選択] ボックスにアプリの名前を入力します。
アプリを選択し、[選択] を選択します。
[レビューと割り当て] を選択します。
Active Directory のセットアップとワークスペースのアクセス許可が完了したら、認可トークンを要求します。

注意

この例では、閲覧者ロールを適用しました。このロールは多くの組み込みロールの 1 つであり、必要以上のアクセス許可が含まれる場合があります。より詳細なロールとアクセス許可を作成できます。詳細については、「Log Analytics ワークスペースへのアクセスを管理する」を参照してください。

承認トークンを要求する

開始する前に、要求を正常に行うために必要なすべての値があることを確認してください。すべての要求には、次が必要です。

Microsoft Entra テナント ID。
あなたのワークスペース ID。
アプリの Microsoft Entra クライアント ID。
アプリの Microsoft Entra クライアントシークレット。

Log Analytics API では、3 つの異なる Microsoft Entra ID OAuth2 フローで Microsoft Entra 認証がサポートされています。

クライアントの資格情報
Authorization code (承認コード)
暗黙

クライアントの資格情報フロー

クライアント資格情報フローでは、トークンは Log Analytics エンドポイントで使用されます。前のステップでアプリを Microsoft Entra ID に登録したときにアプリに提供された資格情報を使い、1 回要求を行ってトークンを受け取ります。

https://api.loganalytics.azure.com エンドポイントを使用します。

クライアント資格情報トークン URL (POST 要求)

    POST /<your-tenant-id>/oauth2/token
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=client_credentials
    &client_id=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

要求が成功すると、アクセストークンが応答で送られてきます。

    {
        token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "access_token": ""eyJ0eXAiOiJKV1QiLCJ.....Ax"
    }

そのトークンを Log Analytics エンドポイントへの要求で使用します。

    POST /v1/workspaces/your workspace id/query?timespan=P1D
    Host: https://api.loganalytics.azure.com
    Content-Type: application/json
    Authorization: Bearer <your access token>

    Body:
    {
    "query": "AzureActivity |summarize count() by Category"
    }

応答の例:

    {
        "tables": [
            {
                "name": "PrimaryResult",
                "columns": [
                    {
                        "name": "OperationName",
                        "type": "string"
                    },
                    {
                        "name": "Level",
                        "type": "string"
                    },
                    {
                        "name": "ActivityStatus",
                        "type": "string"
                    }
                ],
                "rows": [
                    [
                        "Metric Alert",
                        "Informational",
                        "Resolved",
                        ...
                    ],
                    ...
                ]
            },
            ...
        ]
    }

承認コードフロー

サポートされる主な OAuth2 フローは、承認コードを使用して行われます。この方法では、Azure Monitor Log Analytics API の呼び出しに使用するトークンを取得するために 2 つの HTTP 要求が必要です。 2 つの URL (要求ごとに 1 つのエンドポイント) があります。これらの形式については、次のセクションで説明します。

認可コード URL (GET 要求)

    GET https://login.microsoftonline.com/YOUR_Azure AD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=code
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

認可 URL に対する要求を行うとき、client_id は、アプリのプロパティメニューからコピーした、Microsoft Entra アプリのアプリケーション ID です。 redirect_uri は、同じ Microsoft Entra アプリのホームページまたはログイン URL です。要求が成功すると、このエンドポイントによって、承認コードが URL に追加された、サインアップ時に指定したサインインページにリダイレクトされます。次の例を参照してください。

    http://<app-client-id>/?code=AUTHORIZATION_CODE&session_state=STATE_GUID

この時点で、アクセストークンを要求するために必要な認可コードを取得しています。

認可コードトークン URL (POST 要求)

    POST /YOUR_Azure AD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    grant_type=authorization_code
    &client_id=<app client id>
    &code=<auth code fom GET request>
    &redirect_uri=<app-client-id>
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

すべての値は以前と同じですが、いくつかの追加があります。承認コードは、リダイレクトが成功した後に前の要求で受け取ったコードと同じです。コードを、Microsoft Entra アプリから取得したキーと結合します。キーを保存しなかった場合は、それを削除し、Microsoft Entra アプリメニューの [キー] タブから新しいものを作成できます。応答は、次のスキーマを持つトークンを含む JSON 文字列です。トークン値の型が示されています。

応答の例:

    {
        "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
        "expires_in": "3600",
        "ext_expires_in": "1503641912",
        "id_token": "not_needed_for_log_analytics",
        "not_before": "1503638012",
        "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az",
        "resource": "https://api.loganalytics.io",
        "scope": "Data.Read",
        "token_type": "bearer"
    }

この応答のアクセストークン部分は、Authorization: Bearer ヘッダーで Log Analytics API に提示するものです。また、将来、使用しているものが古くなったときに新しい access_token と refresh_token を取得するために、更新トークンを使用することもできます。この要求の形式とエンドポイントは次のとおりです。

    POST /YOUR_AAD_TENANT/oauth2/token HTTP/1.1
    Host: https://login.microsoftonline.com
    Content-Type: application/x-www-form-urlencoded
    
    client_id=<app-client-id>
    &refresh_token=<refresh-token>
    &grant_type=refresh_token
    &resource=https://api.loganalytics.io
    &client_secret=<app-client-secret>

応答の例:

    {
      "token_type": "Bearer",
      "expires_in": "3600",
      "expires_on": "1460404526",
      "resource": "https://api.loganalytics.io",
      "access_token": "eyJ0eXAiOiJKV1QiLCJ.....Ax",
      "refresh_token": "eyJ0esdfiJKV1ljhgYF.....Az"
    }

暗黙的コードフロー

Log Analytics API では、OAuth2 の暗黙的フローがサポートされています。このフローでは、1 つの要求のみが必要ですが、更新トークンは取得できません。

暗黙的コード認可 URL

    GET https://login.microsoftonline.com/YOUR_AAD_TENANT/oauth2/authorize?
    client_id=<app-client-id>
    &response_type=token
    &redirect_uri=<app-redirect-uri>
    &resource=https://api.loganalytics.io

要求が成功すると、次のように URL 内のトークンを使用してリダイレクト URI へのリダイレクトが生成されます。

    http://YOUR_REDIRECT_URI/#access_token=YOUR_ACCESS_TOKEN&token_type=Bearer&expires_in=3600&session_state=STATE_GUID

この access_token は、要求を認可するために Log Analytics API に渡されるときに Authorization: Bearer ヘッダー値として使用できます。

詳細情報

Microsoft Entra での OAuth2 に関するドキュメントについては、以下をご覧ください。

Azure Monitor Log Analytics API にアクセスする

デモ API キーを使用した認証

パブリック API エンドポイント

認証の設定

承認トークンを要求する

クライアントの資格情報フロー

クライアント資格情報トークン URL (POST 要求)

承認コードフロー

認可コード URL (GET 要求)

認可コードトークン URL (POST 要求)

暗黙的コードフロー

暗黙的コード認可 URL

詳細情報

次のステップ

その他のリソース

Azure Monitor Log Analytics API にアクセスする

デモ API キーを使用した認証

パブリック API エンドポイント

認証の設定

承認トークンを要求する

クライアントの資格情報フロー

クライアント資格情報トークン URL (POST 要求)

承認コード フロー

認可コード URL (GET 要求)

認可コード トークン URL (POST 要求)

暗黙的コード フロー

暗黙的コード認可 URL

詳細情報

次のステップ

その他のリソース

承認コードフロー

認可コードトークン URL (POST 要求)

暗黙的コードフロー