次の方法で共有

Azure Monitor のログ インジェスト API

  • [アーティクル]

Azure Monitor のログ インジェスト API を使用すると、REST API 呼び出しまたはクライアント ライブラリ のいずれかを使用して Log Analytics ワークスペースにデータを送信できます。 この API を使うと、サポートされている Azure テーブルまたはユーザーが作成したカスタム テーブルに、データを送信できます。 また、カスタム列で Azure テーブルのスキーマを拡張して、追加のデータを受け取ることもできます。

基本的な操作

REST API を呼び出すことができる任意のアプリケーションから、ログ インジェスト API にデータを送信できます。 これは、ユーザーが作成したカスタム アプリケーションや、API にデータを送信する方法を理解しているアプリケーションやエージェントである場合があります。 そこでは、ターゲット テーブルとワークスペース、および指定された DCR へのアクセス権を持つアプリ登録の資格情報を含む、データ収集ルール (DCR) が指定されています。 DCR で指定されたエンドポイントにデータが送信されます。または、プライベート リンクを使用している場合は、データ収集エンドポイント (DCE) にデータが送信されます。

ユーザーのアプリケーションによって API に送信されるデータは、JSON 形式で書式設定され、DCR で想定されている構造と一致している必要があります。 ただし、ターゲット テーブルの構造と必ずしも一致している必要はありません。これは、DCR には、テーブルの構造に一致するようにデータを変換する変換機能を持たせることができるためです。 DCR を変更することで、API 呼び出しやソース データを変更することなく、ターゲット テーブルとワークスペースを変更できます。

ログ インジェスト API の概要を示す図。

構成

次の表では、ログ インジェスト API を使うために事前に構成する必要がある Azure の各コンポーネントについて説明します。

Note

これらのコンポーネントの構成を自動化する PowerShell スクリプトについては、「Logs ingestion API を使用して Azure Monitor にデータを送信するサンプル コード」をご覧ください。

コンポーネント 関数
アプリの登録とシークレット アプリケーションの登録は、API 呼び出しの認証を行うために使われます。 それには、以下で説明する DCR へのアクセス許可が付与されている必要があります。 API の呼び出しには、アプリケーションのアプリケーション (クライアント) ID とディレクトリ (テナント) ID、およびアプリケーション シークレットの値が含まれます。

「リソースにアクセスできる Microsoft Entra アプリケーションとサービス プリンシパルを作成する」と新しいアプリケーション シークレットの作成に関する記事をご覧ください。
Log Analytics ワークスペースのテーブル Log Analytics ワークスペースのテーブルにデータを送信するには、事前にそれが存在している必要があります。 サポートされている Azure テーブルのいずれかを使うか、利用できる任意の方法を使ってカスタム テーブルを作成することができます。 Azure portal を使ってテーブルを作成すると、必要な場合は変換も含めて、DCR が自動的に作成されます。 他の方法では、次のセクションで説明するように DCR を手動で作成する必要があります。

「カスタム テーブルを作成する」をご覧ください。
データ収集ルール (DCR) Azure Monitor は、データ収集ルール (DCR) を使って、受信データの構造とその処理方法を認識します。 テーブルの構造と受信データが一致しない場合に、ターゲット テーブルと一致するようにソース データを変える変換を、DCR に含めることができます。 変換を使用して、ソース データをフィルター処理し、その他の計算や変換を実行することもできます。

Azure portal を使ってカスタム テーブルを作成すると、ユーザーが提供するサンプル データに基づいて、DCR と変換が自動的に作成されます。 既存のテーブルを使う場合、または別の方法を使ってカスタム テーブルを作成する場合は、次のセクションで示す詳細を使って、DCR を手動で作成する必要があります。

DCR が作成されたら、最初のステップで作成したアプリケーションに対して、それへのアクセスを許可する必要があります。 Azure portal の [監視] メニューで、[データ収集ルール] を選んでから、作成した DCR を選びます。 DCR の [アクセス制御 (IAM)] を選んでから、[ロールの割り当ての追加] を選んで [監視メトリック発行者] ロールを追加します。

エンドポイント

ログ インジェスト API の REST API エンドポイントは、データ収集エンドポイント (DCE) または DCR ログ インジェスト エンドポイントのいずれかになる場合があります。

DCR ログ インジェスト エンドポイントは、直接インジェスト用の DCR を作成すると生成されます。 このエンドポイントを取得するには、Azure portal の JSON ビューで DCR を開きます。 エンドポイントが表示されるには、API のバージョンを最新バージョンに変更する必要がある場合があります。

DCR 内のログ インジェスト エンドポイントを示すスクリーンショット。

DCE は、プライベート リンクを使用して Log Analytics ワークスペースに接続するとき、または DCR にログ インジェスト エンドポイントがない場合にのみ必要です。 これは、古い DCR を使用しているか、DCR を "kind": "Direct" パラメーターなしで作成した場合に当てはまる可能性があります。 詳細については、以下の「データ収集ルール (DCR)」を参照してください。

Note

logsIngestion プロパティは 2024 年 3 月 31 日に追加されました。 この日付より前では、ログ インジェスト API に DCE が必要でした。 エンドポイントを既存の DCR に追加することはできませんが、既存の DCR を既存の DCR と共に使用し続けることは可能です。 DCR エンドポイントに移動する場合は、新しい DCR を作成して既存の DCR を置き換える必要があります。 エンドポイントを持つ DCR が DCE を使用することも可能です。 この場合、DCE を使用するか、DCR を使用する各クライアントについて DCR エンドポイントを使用するかを選択できます。

データ収集ルール (DCR)

Azure portal を使用して Log Analytics ワークスペースにカスタム テーブルを作成すると、ログ インジェスト API で使用できる DCR が自動的に作成されます。 既に存在するテーブルにデータを送信する場合は、DCR を手動で作成する必要があります。 以下のサンプル DCR から始め、テンプレートの次のパラメーターの値を置き換えます。 「Azure Monitor のデータ収集ルール (DCR) を作成および編集する」で説明されている方法のいずれかを使用して、DCR を作成します。

パラメーター 説明
region DCR を作成するリージョン。 これは、Log Analytics ワークスペースのリージョンと DCE と一致している必要があります (使用している場合)。
dataCollectionEndpointId DCE のリソース ID。 DCR インジェスト ポイントを使用している場合は、このパラメーターを削除します。
streamDeclarations 列リストを受信データの列に変更します。 ストリームの名前は、dataFlows での streams の名前と一致しているだけでよいので、変更する必要はありません。
workspaceResourceId Log Analytics ワークスペースのリソース ID。 名前は、dataFlows での destinations の名前と一致しているだけでよいので、変更する必要はありません。
transformKql 受信データに適用される KQL クエリ。 受信データのスキーマがテーブルのスキーマと一致している場合は、受信データを変更しないで渡す source を変換に使用できます。 それ以外の場合は、目的のテーブルのスキーマと一致するようにデータを変換するクエリを使用します。
outputStream データを送信するテーブルの名前。 カスタム テーブルの場合は、プレフィックス "Custom-<テーブル名>" を追加します。. 組み込みテーブルの場合は、プレフィックス "Microsoft-<テーブル名>" を追加します。. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

クライアント ライブラリ

REST API 呼び出しを行うだけでなく、次のクライアント ライブラリを使って、ログ インジェスト API にデータを送信することもできます。 ライブラリには、「構成」で説明されているのと同じコンポーネントが必要です。 これらの各ライブラリの使用例については、「Logs ingestion API を使用して Azure Monitor にデータを送信するサンプル コード」をご覧ください。

REST API の呼び出し

REST API 呼び出しを使って Azure Monitor にデータを送信するには、HTTP 経由で POST 呼び出しを行います。 この呼び出しに必要な詳細については、このセクションで説明します。

URI

URI にはリージョン、DCE または DCR インジェスト エンドポイント、DCR ID、ストリーム名が含まれます。 また、API のバージョンも指定します。

URI は次の形式を使用します。

{Endpoint}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

次に例を示します。

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

DCR Immutable ID は、DCR の作成時にそれに対して生成されます。 これは、Azure portal の DCR の 概要ページから取得できます。

変更できない ID を示すデータ収集ルールのスクリーンショット。

Stream Name は、カスタム データを処理する必要がある DCR 内のStream Nameを示します。

ヘッダー

次の表では、API 呼び出しのヘッダーについて説明します。

ヘッダー 必須 説明
承認 はい クライアント資格情報フローを介して取得されたベアラー トークン。 お使いのクラウドのトークン対象ユーザーの値を使います。

Azure パブリック クラウド - https://monitor.azure.com
21Vianet によって運営される Microsoft Azure クラウド - https://monitor.azure.cn
Azure US Government クラウド - https://monitor.azure.us
Content-Type はい application/json
Content-Encoding いいえ gzip
x-ms-client-request-id いいえ 文字列形式の GUID。 これは、Microsoft がトラブルシューティングの目的で使用できる要求 ID です。

本文​​

呼び出しの本文には、Azure Monitor に送信されるカスタム データが含まれます。 データの形状は、DCR のストリームで想定される形式と一致する項目構造を持つ JSON 配列である必要があります。 API 呼び出し内で単一項目を送信する必要がある場合は、データを単一項目配列として送信する必要があります。

次に例を示します。

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

データ転送に関する問題を防ぐため、要求の本文が UTF-8 で適切にエンコードされていることを確認します。

例

PowerShell を使用した API 呼び出しの例については、「Logs ingestion API を使用して Azure Monitor にデータを送信するサンプル コード」をご覧ください。

サポートするテーブル

インジェスト API に送信されるデータは、次のテーブルに送信できます。

テーブル 説明
カスタム テーブル ユーザーが Log Analytics ワークスペースに作成したカスタム テーブル。 ターゲット テーブルは、データを送信する前に存在している必要があります。 カスタム テーブルには _CL サフィックスが必要です。
Azure テーブル 現在は、次の Azure テーブルがサポートされています。 その他のテーブルは、そのサポートが実装された時点でこの一覧に追加できます。

Note

列名は、文字で始まる必要があり、最大 45 文字の英数字およびアンダースコア (_) で構成できます。 _ResourceId、id、_ResourceId、_SubscriptionId、TenantId、Type、UniqueId、Title は予約されている列名です。 ユーザーが Azure テーブルに追加するカスタム列には、サフィックス _CF が必要です。

制限事項と制約事項

ログ インジェスト API に関連する制限については、「Azure Monitor サービスの制限」を参照してください。

次のステップ