Share via

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 應用程式和服務主體和建立新的應用程式祕密。
資料收集端點 (DCE) 只有在使用私人連結時，才需要 DCE。 它提供應用程式要傳送至的端點。 單一 DCE 可以支援多個 DCR，因此，如果您已經有與 Log Analytics 工作區位於相同區域中的一個 DCE，則可以使用現有的 DCE。 如果您未使用私人連結，則可以使用 DCR 端點。

請參閱建立資料收集端點。
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 將資料行清單變更為傳入資料中的資料行。 您不需要變更資料流的名稱，因為這只需要符合 dataFlows 中的 streams 名稱。
workspaceResourceId Log Analytics 工作區的資源識別碼。 您不需要變更名稱，因為這只需要符合 dataFlows 中的 destinations 名稱。
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 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 監視器服務限制。

下一步