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

  • [アーティクル]

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

基本的な操作

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

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

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

構成

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

Note

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

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

「リソースにアクセスできる Microsoft Entra アプリケーションとサービス プリンシパルを作成する」と新しいアプリケーション シークレットの作成に関する記事をご覧ください。
データ収集エンドポイント (DCE) DCE は、送信するアプリケーションのエンドポイントを提供します。 1 つの DCE で複数の DCR をサポートできるため、Log Analytics ワークスペースと同じリージョンに既に DCE が存在する場合は、既存のものを使用できます。

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

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

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

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

DCR を手動で作成する

既に存在するテーブルにデータを送信する場合は、DCR を手動で作成する必要があります。 ログ インジェスト API 用のサンプル DCR から始めて、テンプレートで次のパラメーターを変更します。 次に、「Azure Monitor のデータ収集ルール (DCR) を作成および編集する」で説明されている方法のいずれかを使って、DCR を作成します。

パラメーター 説明
region DCR を作成するリージョン。 これは、DCE と Log Analytics ワークスペースのリージョンと一致している必要があります。
dataCollectionEndpointId DCE のリソース ID。
streamDeclarations 列リストを受信データの列に変更します。 ストリームの名前は、dataFlows での streams の名前と一致しているだけでよいので、変更する必要はありません。
workspaceResourceId Log Analytics ワークスペースのリソース ID。 名前は、dataFlows での destinations の名前と一致しているだけでよいので、変更する必要はありません。
transformKql 受信データに適用される KQL クエリ。 受信データのスキーマがテーブルのスキーマと一致している場合は、受信データを変更しないで渡す source を変換に使用できます。 それ以外の場合は、テーブルのスキーマと一致するようにデータを変換するクエリを使います。
outputStream データを送信するテーブルの名前。 カスタム テーブルの場合は、プレフィックス "Custom-<テーブル名>" を追加します。. 組み込みテーブルの場合は、プレフィックス "Microsoft-<テーブル名>" を追加します。.

クライアント ライブラリ

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

REST API の呼び出し

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

エンドポイント URL

エンドポイント URI は次の形式を使用します。ここで Data Collection Endpoint と DCR Immutable ID は、DCE と DCR を識別します。 不変の ID は、DCR の作成時にそれに対して生成されます。 これは、Azure portal の DCR の JSON ビューから取得できます。 Stream Name は、カスタム データを処理する必要がある DCR 内のStream Nameを示します。

{Data Collection Endpoint URI}/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

ヘッダー

次の表では、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 サービスの制限」を参照してください。

次のステップ