共用方式為

Azure 監視器中的記錄擷取 API

  • 發行項

Azure 監視器中的記錄擷取 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 中設定的每個元件。

注意

如需自動設定這些元件的 PowerShell 指令碼，請參閱使用記錄擷取 API 將資料傳送至 Azure 監視器的範例程式碼。

元件 函式
應用程式註冊和祕密 應用程式註冊可用來驗證 API 呼叫。 它必須獲授與 DCR 的權限，如下所述。 API 呼叫包含應用程式的應用程式 (用戶端) 識別碼和目錄 (租用戶) 識別碼，以及應用程式祕密的值。

請參閱建立可存取資源的 Microsoft Entra 應用程式和服務主體和建立新的應用程式祕密。
Log Analytics 工作區中的資料表 Log Analytics 工作區中的資料表必須存在，才能將資料傳送至其中。 您可以使用其中一個支援的 Azure 資料表，或使用任何可用的方法建立自訂資料表。 如果您使用 Azure 入口網站來建立資料表，則會為您建立 DCR，並視需要進行轉換。 使用任何其他方法時，您必須手動建立 DCR，如下一節所述。

請參閱建立自訂資料表。
資料收集規則 (DCR) Azure 監視器會使用資料收集規則 (DCR) 來了解傳入資料的結構及其用途。 如果資料表和傳入資料的結構不相符，則 DCR 可以包含轉換，以轉換來源資料以符合目標資料表。 您也可以使用轉換來篩選來源資料，並執行任何其他的計算或轉換。

如果您使用 Azure 入口網站建立自訂資料表，則會根據您提供的範例資料，為您建立 DCR 和轉換。 如果您使用現有的資料表，或使用另一種方法建立自訂資料表，則必須使用下一節中的詳細資料手動建立 DCR。

建立 DCR 之後，您必須為第一個步驟中建立的應用程式授與存取權。 從 Azure 入口網站的 [監視] 功能表中，選取 [資料收集規則]，然後是您建立的 DCR。 選取 DCR 的 [存取控制 (IAM)]，然後選取 [新增角色指派] 以新增監視計量發行者角色。

端點

記錄擷取 API 的 REST API 端點可以是 資料收集端點 （DCE） 或 DCR 記錄擷取端點。

當您建立 DCR 進行直接擷取時，會產生 DCR 記錄擷取端點。 若要擷取此端點，請在 Azure 入口網站 的 JSON 檢視中開啟 DCR。 您可能需要將 API 版本 變更為要顯示的端點最新版本。

顯示 DCR 中記錄擷取端點的螢幕快照。

只有在您使用私人連結連線到 Log Analytics 工作區時，或您的 DCR 不包含記錄擷取端點時，才需要 DCE。 如果您使用較舊的 DCR，或如果您建立沒有 參數的 "kind": "Direct" DCR，則可能是這種情況。 如需詳細資訊，請參閱下面的數據收集規則 （DCR）。

注意

該 logsIngestion 房產於2024年3月31日新增。 在此日期之前，記錄擷取 API 需要 DCE。 無法將端點新增至現有的 DCR，但您可以繼續將任何現有的 DCR 與現有的 DCE 結合使用。 如果您想要移到 DCR 端點，則必須建立一個新的 DCR 來取代現有的 DCR。 具有端點的 DCR 也可以使用 DCE。 在此情況下，您可以為每個使用 DCR 的用戶端選擇是使用 DCE 還是 DCR 端點。

資料收集規則 (DCR)

當您使用 Azure 入口網站 在 Log Analytics 工作區中建立自定義數據表時，會為您建立可與記錄擷取 API 搭配使用的 DCR。 如果您要將資料傳送至已存在的資料表，則必須手動建立 DCR。 從下面的範例 DCR 開始，取代範本中下列參數的值。 使用 Azure 監視器中建立和編輯資料收集規則 （DCR） 中所述的任何方法來建立 DCR。

參數 描述
region 要建立 DCR 的區域。 如果您使用Log Analytics工作區和 DCE 的區域，這必須相符。
dataCollectionEndpointId DCE 的資源識別碼。 如果您使用 DCR 擷取點，請移除此參數。
streamDeclarations 將資料行清單變更為傳入資料中的資料行。 您不需要變更資料流的名稱，因為這只需要符合 dataFlows 中的 streams 名稱。
workspaceResourceId Log Analytics 工作區的資源識別碼。 您不需要變更名稱，因為這只需要符合 dataFlows 中的 destinations 名稱。
transformKql 要套用至傳入資料的 KQL 查詢。 如果傳入資料的結構描述符合資料表的結構描述，則您可以將 source 用於轉換，以在不變更的情況下傳遞傳入資料。 否則，請使用將轉換數據的查詢，以符合目的地數據表架構。
outputStream 要傳送資料的資料表名稱。 針對自訂資料表，新增前置詞 Custom-<table-name>。 針對內建資料表，新增前置詞 Microsoft-<table-name>。 
{
    "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。 程式庫需要設定中所述的相同元件。 如需使用這些程式庫的範例，請參閱使用記錄擷取 API 將資料傳送至 Azure 監視器的範例程式碼。

REST API 呼叫

若要使用 REST API 呼叫將資料傳送至 Azure 監視器，請發出透過 HTTP 的 POST 呼叫。 本節說明此呼叫所需內容的詳細資料。

URI

URI 包含區域、 DCE 或 DCR 擷取端點、DCR識別碼和數據流名稱。 它也會指定 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 入口網站中 DCR 的概觀頁面來擷取它。

顯示固定 ID 之資料收集規則的螢幕擷取畫面。

Stream Name 是指 DCR 中應該要處理自訂資料的資料流。

標題

下表描述 API 呼叫的標頭。

頁首 是必要的嗎？ 描述
授權 Yes 持有人權杖是透過用戶端認證流程取得的。 使用雲端的權杖對象值：

Azure 公用雲端 - https://monitor.azure.com
由 21Vianet Cloud 營運的 Microsoft Azure - https://monitor.azure.cn
Azure 美國政府雲端 - https://monitor.azure.us
內容-類型 Yes application/json
Content-Encoding No gzip
x-ms-client-request-id No 字串格式的 GUID。 這是可由 Microsoft 用於任何疑難排解用途的要求識別碼。

本文

呼叫的本文包含要傳送至 Azure 監視器的自訂資料。 資料的形狀必須是 JSON 陣列，其項目結構符合 DCR 中資料流所預期的格式。 如果需要在 API 呼叫內傳送單一項目，資料應該以單一項目陣列的形式傳送。

例如：

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

請確定要求本文在 UTF-8 中正確編碼，以避免資料傳輸發生任何問題。

範例

如需使用 PowerShell 發出 API 呼叫的範例，請參閱使用記錄擷取 API 將資料傳送至 Azure 監視器的範例程式碼。

支援的資料表

傳送至擷取 API 的資料可以傳送至下列資料表：

資料表 描述
自訂資料表 您在 Log Analytics 工作區中建立的任何自訂資料表。 目標資料表必須先存在，您才能將資料傳送至該資料表。 自訂資料表必須具有 _CL 尾碼。
Azure 資料表 目前支援下列 Azure 資料表。 由於已實作這些資料表的支援，其他資料表可能會新增至此清單。

注意

資料行名稱必須以字母開頭，且最多可以包含 45 個英數字元和底線 (_)。 _ResourceId、id、_ResourceId、_SubscriptionId、TenantId、Type、UniqueId 和 Title 是保留的資料行名稱。 您新增至 Azure 資料表的自訂資料行必須有尾碼 _CF。

限制事項

如需關於記錄內嵌 API 的限制，請參閱 Azure 監視器服務限制。

下一步