共用方式為

教學課程：使用記錄擷取 API 將資料傳送至 Azure 監視器 (Resource Manager 範本)

  • 發行項

Azure 監視器中的記錄擷取 API 可讓您將自訂資料傳送至 Log Analytics 工作區。 本教學課程使用 Azure Resource Manager 範本 (ARM 範本) 逐步解說支援 API 所需的元件設定，然後使用 REST API 和用戶端程式庫為 .NET、Go、Java、JavaScript 和 Python 提供範例應用程式。

注意

本教學課程使用 ARM 範本來設定支援記錄擷取 API 所需的元件。 如需使用 Azure 入口網站 UI 來設定這些元件的類似教學課程，請參閱教學課程：使用記錄擷取 API 將資料傳送至 Azure 監視器記錄 (Azure 入口網站)。

設定記錄擷取 API 所需的步驟如下：

  1. 建立 Microsoft Entra 應用程式來對 API 進行驗證。
  2. 在 Log Analytics 工作區中建立自訂資料表。 這是您要將資料傳送到其中的資料表。
  3. 建立資料收集端點 (DCR) 以將資料導向至目標資料表。
  4. 將 DCR 的存取權提供給 Microsoft Entra 應用程式。
  5. 請參閱使用記錄擷取 API 將資料傳送至 Azure 監視器的範例程式碼，以取得使用記錄擷取 API 來傳送資料的範例程式碼。

注意

本文包含使用 DCR 擷取端點或資料收集端點 （DCE） 的選項。 您可以選擇使用者其中一個，但如果使用私人連結，則需要使用記錄擷取 API 的 DCE。 請參閱 何時需要 DCE？。

必要條件

若要完成本教學課程，您需要：

收集工作區詳細資料

從工作區收集您需要的資訊開始。

在 Azure 入口網站的 [Log Analytics 工作區] 功能表中，移至您的工作區。 在 [屬性] 頁面中，複製 [資源識別碼]，並儲存以供稍後使用。

顯示工作區資源識別碼的螢幕快照。

建立 Microsoft Entra 應用程式

首先，註冊 Microsoft Entra 應用程式以針對 API 進行驗證。 支援任何 Resource Manager 驗證配置，但此教學課程遵循用戶端認證授與流程配置。

  1. 從 Azure 入口網站的 [Microsoft Entra ID] 功能表中，選取 [應用程式註冊]>[新增註冊]。

    顯示應用程式註冊畫面的螢幕快照。

  2. 若預設不適合您的環境，請為應用程式指定名稱並變更租用範圍。 不需要重新導向 URI。

    顯示應用程式詳細數據的螢幕快照。

  3. 註冊之後，您可以檢視應用程式的詳細資料。 請記下應用程式 (租用戶) 識別碼與目錄 (用戶端) 識別碼。 您稍後在程序中會需要這些值。

    顯示應用程式識別碼的螢幕快照。

  4. 產生應用程式用戶端祕密，這類似於建立密碼以搭配使用者名稱一起使用。 選取 [憑證及祕密]>[新增用戶端密碼]。 為祕密指定名稱以識別其用途，然後選取 [過期] 期間。 此處已選取 12 個月的選項。 對於生產實作，您會遵循祕密輪替程序的最佳做法，或使用更安全的驗證模式，例如憑證。

    顯示新應用程式秘密的螢幕快照。

  5. 選取 [新增] 以儲存祕密，然後記下值。 請確定您記錄此值，因為您在離開此頁面之後無法復原此值。 使用與保護密碼相同的安全性措施，因為其為功能對應項。

    顯示新應用程式的秘密值的螢幕快照。

建立資料收集端點

如果您使用 DCR 擷取端點，則不需要 DCE。

在 Log Analytics 工作區中建立新資料表

您必須先建立自訂資料表，才能將資料傳送至該資料表。 本教學課程的資料表將包含下列結構描述中顯示的五個資料行。 每個資料行都必須有 name、type 與 description 屬性。 若未明確指定，則屬性 isHidden 與 isDefaultDisplay 兩者都會預設為 false。 可能的資料類型為 string、int、long、real、boolean、dateTime、guid 與 dynamic。

注意

此教學課程使用來自 Azure Cloud Shell 的 PowerShell，藉由使用 Azure 監視器資料表 API 進行 REST API 呼叫。 您可以使用任何其他有效方法來進行這些呼叫。

重要

自訂資料表必須使用 _CL 的尾碼。

  1. 選取 Azure 入口網站中的 [Cloud Shell] 按鈕，並確保已將環境設定為 [PowerShell]。

    顯示開啟 Cloud Shell 的螢幕快照。

  2. 複製下列 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 可定義收到資料後，資料的處理方式。 這包括：

  • 正要傳送至端點的資料結構描述
  • 轉換，其會在資料傳送至工作區之前套用至資料
  • 轉換資料將傳送至的目的地工作區和資料表

  1. 在 Azure 入口網站的搜尋方塊中，輸入[範本]，然後選取 [部署自訂範本]。

    顯示如何部署自定義範本的螢幕快照。

  2. 選取 [在編輯器中組建您自己的範本]。

    顯示如何在編輯器中建置範本的螢幕快照。

  3. 將下列 ARM 範本貼入編輯器，然後選取 [儲存]。

    顯示如何編輯 ARM 範本的螢幕快照。

    注意此範本所定義 DCR 中的下列詳細資料：

    • streamDeclarations：傳入資料的資料行定義。
    • destinations：目的地工作區。
    • dataFlows：比對資料流與目的地工作區，並指定轉換查詢與目的地資料表。 目的地查詢的輸出會傳送至目的地資料表。
    {
    "$schema": "https://schema.management.azure.com/schemas/2019-08-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."
            }
        }
    },
    "resources": [
        {
            "type": "Microsoft.Insights/dataCollectionRules",
            "name": "[parameters('dataCollectionRuleName')]",
            "location": "[parameters('location')]",
            "apiVersion": "2023-03-11",
            "kind": "Direct",
            "properties": {
                "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'))]"
        }
    }
}

  1. 在 [自訂部署] 畫面中，指定 [訂用帳戶] 和 [資源群組]，以儲存 DCR。 然後提供範本中定義的值。 此值包括 DCR 的名稱，以及您在上一個步驟中收集的工作區資源識別碼。 [位置] 應該與工作區的位置相同。 [區域] 已填入，並且用於 DCR 的位置。

    顯示如何編輯自定義部署值的螢幕快照。

  2. 選取 [檢閱 + 建立]，然後在檢閱詳細資料之後，選取 [建立]。

  3. 部署完成時，展開 [部署詳細資料] 方塊，並選取您的 DCR 以檢視其詳細資料。 選取 [JSON 檢視]。

    顯示 DCR 詳細數據的螢幕快照。

  4. 複製 DCR 的不可變標識碼和記錄擷取 URI。 當您使用 API 將資料傳送至 Azure 監視器時 ，您將使用這些資料。

    顯示 DCR JSON 檢視的螢幕快照。

將權限指派給 DCR

建立 DCR 之後，必須授與應用程式權限。 許可權可讓任何使用正確應用程式識別碼和應用程式金鑰的應用程式，將數據傳送至新的 DCR。

  1. 從 Azure 入口網站中的 DCR，選取 [存取控制 (IAM)] [新增角色指派]>。

    顯示將自定義角色指派新增至 DCR 的螢幕快照。

  2. 選取 [監視計量發行者]，然後選取 [下一步]。 您可以改用 Microsoft.Insights/Telemetry/Write 資料動作來建立自訂動作。

    顯示選取 DCR 角色指派角色的螢幕快照。

  3. 為 [將存取全指派給] 選取 [使用者、群組或服務主體]，並選擇 [選取成員]。 選取您建立的應用程式，並選擇 [選取]。

    顯示選取 DCR 角色指派成員的螢幕快照。

  4. 選取 [檢閱 + 指派]，然後先確認詳細資料，再儲存您的角色指派。

    顯示儲存 DCR 角色指派的螢幕快照。

範例指令碼

請參閱使用記錄擷取 API 將資料傳送至 Azure 監視器的範例程式碼，以取得使用本教學課程中建立的元件的範例程式碼。

下一步