記錄 Azure 監視器中的擷取 API

  • 發行項

Azure 監視器中的記錄擷取 API 可讓您使用 REST API 呼叫 或 用戶端連結庫將數據傳送至 Log Analytics 工作區。 API 可讓您將資料傳送至支援的 Azure 資料表或您建立的自定義資料表。 您也可以 使用自定義數據行 擴充 Azure 資料表的架構，以接受其他數據。

基本作業

數據可以從任何可進行 REST API 呼叫的應用程式傳送至記錄擷取 API。 這可能是您建立的自定義應用程式，或者可能是瞭解如何將數據傳送至 API 的應用程式或代理程式。 應用程式會將數據傳送至 資料收集端點 （DCE），這是 Azure 訂用帳戶的唯一連接點。 它會指定 資料收集規則 （DCR）， 其中包含目標數據表和工作區，以及具有指定 DCR 存取權之應用程式註冊的認證。

應用程式傳送至 API 的數據必須以 JSON 格式化，並符合 DCR 預期的結構。 它不一定需要比對目標數據表的結構，因為 DCR 可以包含 轉換 ，以轉換數據以符合數據表的結構。 您可以修改 DCR 來修改目標數據表和工作區，而不需要變更 API 呼叫或源數據。

顯示記錄擷取 API 概觀的圖表。

組態

下表描述您在使用記錄擷取 API 之前，必須先設定的每個 Azure 元件。

注意

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

元件 函式
應用程式註冊和秘密 應用程式註冊可用來驗證 API 呼叫。 它必須授與 DCR 的許可權，如下所述。 API 呼叫包含 應用程式的應用程式（用戶端）標識碼 和 目錄（租使用者）標識碼 ，以及 應用程式秘密的值 。

請參閱 建立可存取資源的 Microsoft Entra 應用程式和服務主體和 建立新的應用程式秘密。
資料收集端點 （DCE） DCE 會提供要傳送至之應用程式的端點。 單一 DCE 可以支援多個 DCR，因此，如果您已經有與 Log Analytics 工作區位於相同區域中的現有 DCE，則可以使用現有的 DCE。

請參閱 建立數據收集端點。
Log Analytics 工作區中的數據表 Log Analytics 工作區中的數據表必須存在，才能將數據傳送至該工作區。 您可以使用其中 一個支援的 Azure 資料表 ，或使用任何可用的方法建立自定義數據表。 如果您使用 Azure 入口網站 來建立數據表，則會為您建立 DCR，並視需要包括轉換。 使用任何其他方法時，您必須手動建立 DCR，如下一節所述。

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

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

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

手動建立 DCR

如果您要將數據傳送至已經存在的數據表，則必須手動建立 DCR。 從記錄擷取 API 的範例 DCR 開始，並在範本中修改下列參數。 然後使用 Azure 監視器中建立和編輯資料收集規則 （DCR） 中所述的任何方法來建立 DCR。

參數 描述
region 要建立 DCR 的區域。 這必須符合 DCE 和 Log Analytics 工作區的區域。
dataCollectionEndpointId DCE 的資源識別碼。
streamDeclarations 將數據列清單變更為傳入資料中的數據行。 您不需要變更數據流的名稱，因為這只需要符合 streams 中的 dataFlows名稱。
workspaceResourceId Log Analytics 工作區的資源標識碼。 您不需要變更名稱，因為這只需要符合 destinations 中的 dataFlows名稱。
transformKql 要套用至傳入數據的 KQL 查詢。 如果連入數據的架構符合數據表的架構，則您可以使用 source 轉換來傳遞傳入數據不變。 否則，請使用將轉換數據的查詢來比對數據表架構。
outputStream 要傳送數據的數據表名稱。 針對自定義數據表，新增 Custom-table-name<> 前置詞。 針對內建數據表，新增 Microsoft-table-name<> 前置詞。

用戶端程式庫

除了進行 REST API 呼叫之外，您還可以使用下列用戶端連結庫將數據傳送至記錄擷取 API。 連結庫需要組態中所述的相同元件。 如需使用這些連結庫的範例，請參閱 使用記錄擷取 API 將數據傳送至 Azure 監視器的範例程式代碼。

REST API 呼叫

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

端點 URI

端點 URI 會使用下列格式，其中 Data Collection Endpoint 和 DCR Immutable ID 會識別 DCE 和 DCR。 建立 DCR 時，會產生不可變標識符。 您可以從 Azure 入口網站 中 DCR 的 JSON 檢視擷取它。 Stream Name是指 DCR 中應該處理自訂數據的數據流。

{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 呼叫的標頭。

頁首 必要? 描述
授權 Yes 透過客戶端認證流程取得的持有人令牌。 使用雲端的權杖物件值：

Azure 公用雲端 - https://monitor.azure.com
由 21Vianet 雲端運作的 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 監視器服務限制。

下一步