チュートリアル: ログインジェスト API (Resource Manager テンプレート) を使用して Azure Monitor にデータを送信する

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

Azure Monitor のログインジェスト API を使用すると、Log Analytics ワークスペースにカスタムデータを送信できます。このチュートリアルでは、Azure Resource Manager テンプレート (ARM テンプレート) を使用して、API をサポートするために必要なコンポーネントの構成について説明し、続いて、.NET、Go、Java、JavaScript、Python 用の REST API とクライアントライブラリの両方を使用するサンプルアプリケーションを提供します。

Note

このチュートリアルでは、ARM テンプレートを使用して、ログインジェスト API をサポートするために必要なコンポーネントを構成します。 Azure portal を使用してこれらのコンポーネントを構成する同様のチュートリアルについては、「チュートリアル: ログインジェスト API を使用して Azure Monitor Logs にデータを送信する (Azure portal)」を参照してください。

ログインジェスト API を構成するために必要な手順は次のとおりです。

API に対して認証を行う Microsoft Entra アプリケーションを作成します。
データを受信するためのデータコレクションエンドポイント (DCE) を作成する。
Log Analytics ワークスペースにカスタムテーブルを作成する。これが、データの送信先のテーブルとなる。
データをターゲットテーブルに転送するためのデータ収集ルール (DCR) を作成する。
Microsoft Entra アプリケーションに DCR へのアクセスを付与する。
ログインジェスト API を使用してデータを送信するサンプルコードについては、「ログインジェスト API を使用して Azure Monitor にデータを送信するサンプルコード」を参照してください。

前提条件

このチュートリアルを完了するには、次のものが必要です。

少なくとも共同作成者権限がある Log Analytics ワークスペース。
ワークスペースでDCR オブジェクトを作成するためのアクセス許可。

ワークスペースの詳細を収集する

まず、ワークスペースから必要となる情報を収集します。

Azure portal の [Log Analytics ワークスペース] メニューでワークスペースにアクセスします。 [プロパティ] ページで、[リソース ID] をコピーして、後で使用するために保存します。

Microsoft Entra アプリケーションを作成する

まず、API に対して認証する Microsoft Entra アプリケーションを登録します。 Resource Manager 認証スキームはサポートされていますが、このチュートリアルでは、クライアント資格情報付与フロースキームに従います。

Azure portal の [Microsoft Entra ID] メニューで、[アプリの登録]>[新規登録] を選択します。
アプリケーションに名前を付け、既定値が環境に適していない場合はテナントのスコープを変更します。 [リダイレクト URI] は必要ありません。
登録されると、アプリケーションの詳細が表示されます。 [アプリケーション (クライアント) ID] と [ディレクトリ (テナント) ID] をメモします。これらの値は、このプロセスで後で必要になります。
アプリケーションクライアントシークレットを生成します。これは、ユーザー名と共に使用するパスワードの作成と似ています。 [証明書およびシークレット]>[新しいクライアントシークレット] の順に選択します。シークレットに用途がわかるような名前を指定し、[有効期限] の期間を選択します。ここではオプション [12 か月] が選択されています。運用環境の実装では、シークレットのローテーション手順のベストプラクティスに従うか、より安全な認証モード (証明書など) を使用します。
[追加] を選択してシークレットを保存し、[値] をメモします。このページを離れると、この値を回復することはできないため、記録しておいてください。パスワードと同等の機能を持つため、パスワードを保管する場合と同じセキュリティ対策を使用します。

データ収集エンドポイントを作成する

Azure Monitor に送信されるデータを受け入れるために、DCE が必要となります。 DCE を構成して DCR にリンクしたら、アプリケーションから HTTP 経由でデータを送信できます。 DCE は、DCR およびデータが送信される Log Analytics ワークスペースと同じリージョンにある必要があります。

Azure portal の検索ボックスに、「テンプレート」と入力して、[カスタムテンプレートのデプロイ] を選択します。
[Build your own template in the editor] (エディターで独自のテンプレートをビルド) を選択します。

次の ARM テンプレートをエディターに貼り付けてから、[保存] を選択します。パラメーターの値を指定するので、このテンプレートを変更する必要はありません。

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionEndpointName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Endpoint to create."
            }
        },
        "location": {
            "type": "string",
            "defaultValue": "westus2",
            "metadata": {
                "description": "Specifies the location for the Data Collection Endpoint."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionEndpoints",
            "name": "[parameters('dataCollectionEndpointName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-04-01",
            "properties": {
                "networkAcls": {
                "publicNetworkAccess": "Enabled"
                }
            }
        }
    ],
    "outputs": {
        "dataCollectionEndpointId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionEndpoints', parameters('dataCollectionEndpointName'))]"
        }
    }
}

[カスタムデプロイ] 画面で、DCR を格納する [サブスクリプション] と [リソースグループ] を指定し、DCE の [名前] のような値を指定します。 [場所] は、ワークスペースと同じ場所にする必要があります。 [リージョン] は既に設定されていて、DCE の場所に使用されます。
[確認と作成] を選択し、詳細を確認したら [作成] を選択します。
[JSON 表示] を選択して、DCE のその他の詳細を表示します。 リソース ID と logsIngestion エンドポイント をコピーします。後の手順で必要になります。

Log Analytics ワークスペースに新しいテーブルを作成する

データを送信する前に、カスタムテーブルを作成する必要があります。このチュートリアルのテーブルには、以下のスキーマで示している 5 つの列が含まれています。 name、type、description の各プロパティは、列ごとに必須です。明示的に指定されていない場合、isHidden および isDefaultDisplay プロパティは両方とも既定で false に設定されます。使用できるデータ型は string、int、long、real、boolean、dateTime、guid、dynamic です。

Note

このチュートリアルでは、Azure Cloud Shell の PowerShell を使用し、Azure Monitor の Tables API を使用して REST API 呼び出しを行います。これらの呼び出しは、他の有効な方法を使用して行うことができます。

重要

カスタムテーブルには、_CL というサフィックスを使用する必要があります。

Azure portal で [Cloud Shell] ボタンを選択して、環境が PowerShellに設定されていることを確認します。

次の PowerShell コードをコピーし、Invoke-AzRestMethod コマンドの Path パラメーターの変数をワークスペースの適切な値に置き換えます。それを Cloud Shell のプロンプトに貼り付けて、実行します。

$tableParams = @'
{
    "properties": {
        "schema": {
            "name": "MyTable_CL",
            "columns": [
                {
                    "name": "TimeGenerated",
                    "type": "datetime",
                    "description": "The time at which the data was generated"
                },
               {
                    "name": "Computer",
                    "type": "string",
                    "description": "The computer that generated the data"
                },
                {
                    "name": "AdditionalContext",
                    "type": "dynamic",
                    "description": "Additional message properties"
                },
                {
                    "name": "CounterName",
                    "type": "string",
                    "description": "Name of the counter"
                },
                {
                    "name": "CounterValue",
                    "type": "real",
                    "description": "Value collected for the counter"
                }
            ]
        }
    }
}
'@

Invoke-AzRestMethod -Path "/subscriptions/{subscription}/resourcegroups/{resourcegroup}/providers/microsoft.operationalinsights/workspaces/{workspace}/tables/MyTable_CL?api-version=2022-10-01" -Method PUT -payload $tableParams

データ収集ルールを作成する

DCR は、受信したデータの処理方法を定義します。これには次のものが含まれます

エンドポイントに送信されるデータのスキーマ
ワークスペースに送信される前にデータに適用される変換
変換されたデータの送信先となるワークスペースとテーブル

Azure portal の検索ボックスに、「テンプレート」と入力して、[カスタムテンプレートのデプロイ] を選択します。
[Build your own template in the editor] (エディターで独自のテンプレートをビルド) を選択します。

次の ARM テンプレートをエディターに貼り付けてから、[保存] を選択します。

このテンプレートで定義されている DCR の次の詳細に注意してください。

dataCollectionEndpointId: データ収集エンドポイントのリソース ID。
streamDeclarations: 受信データの列定義。
destinations: 宛先のワークスペース。
dataFlows: ストリームを送信先ワークスペースと照合し、変換クエリと送信先テーブルを指定します。変換先テーブルに送信されるのは、変換先クエリの出力です。

{
    "$schema": "https://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
    "contentVersion": "1.0.0.0",
    "parameters": {
        "dataCollectionRuleName": {
            "type": "string",
            "metadata": {
                "description": "Specifies the name of the Data Collection Rule to create."
            }
        },
        "location": {
            "type": "string",
            "metadata": {
                "description": "Specifies the location in which to create the Data Collection Rule."
            }
        },
        "workspaceResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Log Analytics workspace to use."
            }
        },
        "endpointResourceId": {
            "type": "string",
            "metadata": {
                "description": "Specifies the Azure resource ID of the Data Collection Endpoint to use."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2021-09-01-preview",
            "properties": {
                "dataCollectionEndpointId": "[parameters('endpointResourceId')]",
                "streamDeclarations": {
                    "Custom-MyTableRawData": {
                        "columns": [
                            {
                                "name": "Time",
                                "type": "datetime"
                            },
                            {
                                "name": "Computer",
                                "type": "string"
                            },
                            {
                                "name": "AdditionalContext",
                                "type": "string"
                            },
                            {
                                "name": "CounterName",
                                "type": "string"
                            },
                            {
                                "name": "CounterValue",
                                "type": "real"
                            }
                        ]
                    }
                },
                "destinations": {
                    "logAnalytics": [
                        {
                            "workspaceResourceId": "[parameters('workspaceResourceId')]",
                            "name": "myworkspace"
                        }
                    ]
                },
                "dataFlows": [
                    {
                        "streams": [
                            "Custom-MyTableRawData"
                        ],
                        "destinations": [
                            "myworkspace"
                        ],
                        "transformKql": "source | extend jsonContext = parse_json(AdditionalContext) | project TimeGenerated = Time, Computer, AdditionalContext = jsonContext, CounterName=tostring(jsonContext.CounterName), CounterValue=toreal(jsonContext.CounterValue)",
                        "outputStream": "Custom-MyTable_CL"
                    }
                ]
            }
        }
    ],
    "outputs": {
        "dataCollectionRuleId": {
            "type": "string",
            "value": "[resourceId('Microsoft.Insights/dataCollectionRules', parameters('dataCollectionRuleName'))]"
        }
    }
}

[カスタムデプロイ] 画面で、DCR を格納する [サブスクリプション] と [リソースグループ] を指定します。次に、テンプレートで定義されている値を指定します。値には、DCR の [名前] と、前の手順で収集した [ワークスペースリソース ID] が含まれます。 [場所] は、ワークスペースと同じ場所にする必要があります。 [リージョン] は既に設定されていて、DCR の場所に使用されます。
[確認と作成] を選択し、詳細を確認したら [作成] を選択します。
デプロイが完了したら、[デプロイの詳細] ボックスを展開し、DCR を選択して詳細を表示します。 [JSON ビュー] を選択します。
DCR の不変 ID をコピーします。これは、後の手順で API を使用してサンプルデータを送信するときに使用します。

注意

DCR のすべてのプロパティ (変換など) が、それらのプロパティを使用して DCR が正常に作成された場合でも、Azure portal に表示されないことがあります。

DCR にアクセス許可を割り当てる

DCR を作成したら、アプリケーションにアクセス許可を付与する必要があります。アクセス許可により、アプリケーションで正しいアプリケーション ID とアプリケーションキーが使用して、新しい DCE と DCR にデータを送信できるようになります。

Azure portal の DCR で、[アクセスの制御 (IAM)]>[ロールの割り当ての追加] の順に選択します。
[監視メトリックパブリッシャー] を選択し [次へ] を選択します。代わりに、Microsoft.Insights/Telemetry/Write データアクションを使用してカスタムアクションを作成することもできます。
[アクセス権の割り当て先] で [ユーザー、グループ、またはサービスプリンシパル] を選択し、[メンバーの選択] を選択します。作成したアプリケーションを選択して、[選択] を選択します。
[確認と割り当て] を選択して、ロールの割り当てを保存する前に詳細を確認します。

サンプルコード

このチュートリアルで作成したコンポーネントを使用したサンプルコードについては、「ログインジェスト API を使用して Azure Monitor にデータを送信するサンプルコード」を参照してください。

チュートリアル: ログインジェスト API (Resource Manager テンプレート) を使用して Azure Monitor にデータを送信する

前提条件

ワークスペースの詳細を収集する

Microsoft Entra アプリケーションを作成する

データ収集エンドポイントを作成する

Log Analytics ワークスペースに新しいテーブルを作成する

データ収集ルールを作成する

DCR にアクセス許可を割り当てる

サンプルコード

次のステップ

その他のリソース

チュートリアル: ログ インジェスト API (Resource Manager テンプレート) を使用して Azure Monitor にデータを送信する

前提条件

ワークスペースの詳細を収集する

Microsoft Entra アプリケーションを作成する

データ収集エンドポイントを作成する

Log Analytics ワークスペースに新しいテーブルを作成する

データ収集ルールを作成する

DCR にアクセス許可を割り当てる

サンプル コード

次のステップ

その他のリソース

チュートリアル: ログインジェスト API (Resource Manager テンプレート) を使用して Azure Monitor にデータを送信する

サンプルコード