使用 HTTP 資料收集器 API 將記錄資料傳送至 Azure 監視器(已淘汰)

本文說明如何使用 HTTP 資料收集器 API,從 REST API 用戶端將記錄資料傳送至 Azure 監視器。 它描述如何格式化腳本或應用程式收集的數據、將其包含在要求中,以及讓 Azure 監視器授權該要求。 我們提供 Azure PowerShell、C# 和 Python 的範例。

注意

Azure 監視器 HTTP 資料收集器 API 已被取代,且自 2026 年 9 月 14 日起將不再運作。 它已由 記錄擷取 API 取代。

概念

您可以使用 HTTP 資料收集器 API,從任何可呼叫 REST API 的用戶端,將記錄數據傳送至 Azure 監視器中的 Log Analytics 工作區。 用戶端可能是從 Azure 或其他雲端收集管理資料的 Azure 自動化 Runbook,或者可能是使用 Azure 監視器來合併和分析記錄數據的替代管理系統。

Log Analytics 工作區中的所有數據都會儲存為具有特定記錄類型的記錄。 您可以將資料格式化為以 JavaScript 物件表示法 (JSON) 中的多個記錄傳送至 HTTP 資料收集器 API。 當您提交數據時,系統會在存放庫中為要求承載中的每個記錄建立個別記錄。

Screenshot illustrating the HTTP Data Collector overview.

建立要求

若要使用 HTTP 資料收集器 API,您可以建立 POST 要求,其中包含要以 JSON 傳送的數據。 接下來的三個數據表會列出每個要求所需的屬性。 本文稍後會更詳細地描述每個屬性。

要求 URI

屬性 屬性
方法 POST
URI <https:// CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01>
內容類型 application/json

要求 URI 參數

參數 描述
CustomerID Log Analytics 工作區的唯一標識碼。
資源 API 資源名稱:/api/logs。
API 版本 要與這個要求搭配使用的 API 版本。 目前版本是 2016-04-01。

要求標頭

標頭 描述
授權 授權簽章。 本文稍後,您可以閱讀如何建立 HMAC-SHA256 標頭。
記錄類型 指定要送出之數據的記錄類型。 它只能包含字母、數位和底線 (_) 字元,而且不能超過 100 個字元。
x-ms-date 要求的處理日期,格式為 RFC 1123
x-ms-AzureResourceId 應該與數據相關聯的 Azure 資源資源資源識別碼。 它會填入_ResourceId屬性,並允許數據包含在資源內容查詢中。 如果未指定此欄位,資料將不會包含在資源內容查詢中。
time-generated-field 數據中包含資料項時間戳的功能變數名稱。 如果您指定欄位,則會將其內容用於 TimeGenerated。 如果您未指定此欄位,TimeGenerated 預設值是訊息內嵌的時間。 郵件欄位的內容應遵循 ISO 8601 格式 YYYY-MM-DDThh:mm:ssZ。 產生的時間值不能早于 2 天前收到時間或未來超過一天。 在這種情況下,將會使用訊息的內嵌時間。

授權

對 Azure 監視器 HTTP 資料收集器 API 的任何要求都必須包含授權標頭。 若要驗證要求,請使用發出要求之工作區的主要或次要金鑰簽署要求。 然後,以要求一部分的形式傳遞該簽章。

以下是授權標頭的格式:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID 是 Log Analytics 工作區的唯一識別碼。 簽章 是以 雜湊為基礎的訊息驗證碼 (HMAC), 其建構自要求,然後使用 SHA256 演算法 進行 計算。 然後,您可以使用 Base64 編碼來編碼它。

使用此格式來編碼 SharedKey 簽章字串:

StringToSign = VERB + "\n" +
                  Content-Length + "\n" +
                  Content-Type + "\n" +
                  "x-ms-date:" + x-ms-date + "\n" +
                  "/api/logs";

以下是簽章字串的範例:

POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs

當您有簽章字串時,請使用 UTF-8 編碼字串上的 HMAC-SHA256 演算法進行編碼,然後將結果編碼為 Base64。 使用此格式:

Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))

下一節中的範例有範例程式碼,可協助您建立授權標頭。

要求本文

訊息的本文必須位於 JSON 中。 它必須包含一或多個具有屬性名稱和值組的記錄,格式如下。 屬性名稱只能包含字母、數位和底線 (_) 字元。

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

您可以使用下列格式,以單一要求一起批次處理多個記錄。 所有記錄都必須是相同的記錄類型。

[
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    },
    {
        "property 1": "value1",
        "property 2": "value2",
        "property 3": "value3",
        "property 4": "value4"
    }
]

記錄類型和屬性

當您透過 Azure 監視器 HTTP 資料收集器 API 提交資料時,您可以定義自訂記錄類型。 目前,您無法將資料寫入其他資料類型和解決方案所建立的現有記錄類型。 Azure 監視器會讀取傳入的資料,然後建立符合您輸入之值資料類型的屬性。

資料收集器 API 的每個要求都必須包含 記錄類型名稱的 Log-Type 標頭。 _CL 尾碼 會自動附加至您輸入的名稱,以將其與其他記錄類型區別為自訂記錄檔。 例如,如果您輸入名稱 MyNewRecordType,Azure 監視器會建立具有類型 MyNewRecordType_CL 的記錄。 這有助於確保使用者建立的類型名稱與目前或未來 Microsoft 解決方案中隨附的類型名稱之間沒有任何衝突。

若要識別屬性的資料類型,Azure 監視器會將尾碼新增至屬性名稱。 如果屬性包含 Null 值,該屬性就不會包含在該記錄中。 下表列出屬性資料類型和對應的尾碼:

屬性資料類型 尾碼
String _s
布林值 _B
雙重 _D
日期時間 _t
GUID (儲存為字串) _G

注意

看似 GUID 的字串值會指定_g尾碼,並格式化為 GUID,即使傳入值不包含連字號也一樣。 例如,「8145d822-13a7-44ad-859c-36f31a84f6dd」 和 「8145d82213a744ad859c36f31a84f6dd」 會儲存為 「8145d822-13a7-44ad-859c-36f31a84f6dd」。 這個字串與另一個字串之間的唯一差異是名稱中的_g,如果未在輸入中提供破折號,則會插入破折號。

Azure 監視器針對每個屬性所使用的資料類型取決於新記錄的記錄類型是否已經存在。

  • 如果記錄類型不存在,Azure 監視器會使用 JSON 類型推斷來建立新的記錄類型,以判斷新記錄之每個屬性的資料類型。
  • 如果記錄類型確實存在,Azure 監視器會嘗試根據現有的屬性建立新的記錄。 如果新記錄中屬性的資料類型不相符且無法轉換成現有的類型,或者如果記錄包含不存在的屬性,Azure 監視器會建立具有相關尾碼的新屬性。

例如,下列提交專案會建立具有三個屬性 、number_d boolean_b string_s 的記錄:

Screenshot of sample record 1.

如果您要提交下一個專案,且所有格式化為字串的值,則屬性不會變更。 您可以將值轉換成現有的資料類型。

Screenshot of sample record 2.

但是,如果您接著進行下一次提交,Azure 監視器會建立新的屬性 boolean_d string_d 。 您無法轉換這些值。

Screenshot of sample record 3.

如果您接著提交下列專案,在建立記錄類型之前,Azure 監視器會建立具有三個屬性、 number_s boolean_s string_s的 記錄。 在此專案中,每個初始值都會格式化為字串:

Screenshot of sample record 4.

保留的屬性

下列屬性是保留的,不應用於自訂記錄類型。 如果您的承載包含下列任何屬性名稱,您會收到錯誤:

  • tenant
  • TimeGenerated
  • RawData

資料限制

張貼至 Azure 監視器資料收集 API 的資料受限於特定條件約束:

  • 每個貼文最多 30 MB 到 Azure 監視器資料收集器 API。 這是單一貼文的大小限制。 如果單一貼文中的資料超過 30 MB,您應該將資料分割成較小的區塊,並同時傳送。
  • 域值的上限為 32 KB。 如果欄位值大於 32 KB,資料將會被截斷。
  • 建議指定類型的最多 50 個欄位。 對於使用性和搜尋體驗觀點而言,這是一個實際的限制。
  • Log Analytics 工作區中的資料表僅支援最多 500 個數據行(在本文中稱為欄位)。
  • 資料行名稱最多 45 個字元。

傳回碼

HTTP 狀態代碼 200 表示已收到要求進行處理。 這表示作業已順利完成。

下表列出服務可能會傳回的完整狀態代碼集:

代碼 狀態 錯誤碼 描述
200 確定 已成功接受要求。
400 錯誤要求 InactiveCustomer 工作區已關閉。
400 錯誤要求 InvalidApiVersion 您指定的 API 版本無法由服務辨識。
400 錯誤要求 InvalidCustomerId 指定的工作區標識碼無效。
400 錯誤要求 InvalidDataFormat 送出無效的 JSON。 回應本文可能包含如何解決錯誤的詳細資訊。
400 錯誤要求 InvalidLogType 指定的記錄類型包含特殊字元或數值。
400 錯誤要求 MissingApiVersion 未指定 API 版本。
400 錯誤要求 MissingContentType 未指定內容類型。
400 錯誤要求 MissingLogType 未指定必要的值記錄類型。
400 錯誤要求 UnsupportedContentType 內容類型未設定為 application/json
403 禁止 InvalidAuthorization 服務無法驗證要求。 確認工作區標識碼和聯機密鑰有效。
404 找不到 提供的 URL 不正確,或要求太大。
429 過多要求 服務遇到來自您帳戶的大量數據。 請稍後再重試要求。
500 內部伺服器錯誤 UnspecifiedError 服務發生內部錯誤。 請重試要求。
503 服務無法使用 ServiceUnavailable 服務目前無法接收要求。 請重試您的要求。

查詢資料

若要查詢 Azure 監視器 HTTP 資料收集器 API 送出的數據,請搜尋類型等於您指定的 LogType 值,並附加_CL的記錄。 例如,如果您使用 MyCustomLog,則會使用 MyCustomLog_CL傳回所有記錄。

範例要求

本節範例示範如何使用各種程序設計語言將數據提交至 Azure 監視器 HTTP 數據收集器 API。

針對每個範例,執行下列動作來設定授權標頭的變數:

  1. 在 Azure 入口網站 中,找出您的Log Analytics工作區。
  2. 選取 [ 代理程式]。
  3. 在工作區標識碼右側,選取 [複製] 圖示,然後將標識碼貼上為 [客戶標識符] 變數的值
  4. 在 [主要金鑰] 右側,選取 [複製] 圖示,然後將標識碼貼上為共用金鑰變數的值

或者,您可以變更記錄類型和 JSON 數據的變數。

# Replace with your Workspace ID
$CustomerId = "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx"  

# Replace with your Primary Key
$SharedKey = "xxxxxxxxxxxxxxxxxxxxxxxxxxxxxx"

# Specify the name of the record type that you'll be creating
$LogType = "MyRecordType"

# Optional name of a field that includes the timestamp for the data. If the time field is not specified, Azure Monitor assumes the time is the message ingestion time
$TimeStampField = ""


# Create two records with the same set of properties to create
$json = @"
[{  "StringValue": "MyString1",
    "NumberValue": 42,
    "BooleanValue": true,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "9909ED01-A74C-4874-8ABF-D2678E3AE23D"
},
{   "StringValue": "MyString2",
    "NumberValue": 43,
    "BooleanValue": false,
    "DateValue": "2019-09-12T20:00:00.625Z",
    "GUIDValue": "8809ED01-A74C-4874-8ABF-D2678E3AE23D"
}]
"@

# Create the function to create the authorization signature
Function Build-Signature ($customerId, $sharedKey, $date, $contentLength, $method, $contentType, $resource)
{
    $xHeaders = "x-ms-date:" + $date
    $stringToHash = $method + "`n" + $contentLength + "`n" + $contentType + "`n" + $xHeaders + "`n" + $resource

    $bytesToHash = [Text.Encoding]::UTF8.GetBytes($stringToHash)
    $keyBytes = [Convert]::FromBase64String($sharedKey)

    $sha256 = New-Object System.Security.Cryptography.HMACSHA256
    $sha256.Key = $keyBytes
    $calculatedHash = $sha256.ComputeHash($bytesToHash)
    $encodedHash = [Convert]::ToBase64String($calculatedHash)
    $authorization = 'SharedKey {0}:{1}' -f $customerId,$encodedHash
    return $authorization
}

# Create the function to create and post the request
Function Post-LogAnalyticsData($customerId, $sharedKey, $body, $logType)
{
    $method = "POST"
    $contentType = "application/json"
    $resource = "/api/logs"
    $rfc1123date = [DateTime]::UtcNow.ToString("r")
    $contentLength = $body.Length
    $signature = Build-Signature `
        -customerId $customerId `
        -sharedKey $sharedKey `
        -date $rfc1123date `
        -contentLength $contentLength `
        -method $method `
        -contentType $contentType `
        -resource $resource
    $uri = "https://" + $customerId + ".ods.opinsights.azure.com" + $resource + "?api-version=2016-04-01"

    $headers = @{
        "Authorization" = $signature;
        "Log-Type" = $logType;
        "x-ms-date" = $rfc1123date;
        "time-generated-field" = $TimeStampField;
    }

    $response = Invoke-WebRequest -Uri $uri -Method $method -ContentType $contentType -Headers $headers -Body $body -UseBasicParsing
    return $response.StatusCode

}

# Submit the data to the API endpoint
Post-LogAnalyticsData -customerId $customerId -sharedKey $sharedKey -body ([System.Text.Encoding]::UTF8.GetBytes($json)) -logType $logType  

替代方案和考慮

雖然數據收集器 API 應該涵蓋大部分的需求,因為您將自由格式數據收集到 Azure 記錄中,但您可能需要替代方法來克服 API 的一些限制。 下表列出您的選項,包括主要考慮:

替代函式 描述 最適合
自定義事件:Application Insights 中的原生 SDK 型擷取 Application Insights 通常透過應用程式內的 SDK 進行檢測,可讓您透過自定義事件傳送自定義數據。
  • 應用程式內產生的數據,但 SDK 不會透過其中一個預設數據類型(要求、相依性、例外狀況等等)挑選。
  • 最常與 Application Insights 中的其他應用程式數據相互關聯的數據。
Azure 監視器記錄中的數據收集器 API Azure 監視器記錄中的數據收集器 API 是內嵌數據的完全開放方式。 JSON 物件中格式化的任何數據都可以在這裡傳送。 傳送之後,它會在監視記錄中進行處理並可供使用,以便與監視記錄中的其他數據或其他 Application Insights 數據相互關聯。

將數據當作檔案上傳至 Azure Blob 儲存體 Blob 相當容易,其中會處理檔案,然後上傳至 Log Analytics。 如需範例實作,請參閱 使用數據收集器 API 建立數據管線。
  • 在 Application Insights 內檢測的應用程式內不一定產生的數據。
    範例包括查閱和事實數據表、參考數據、預先匯總的統計數據等等。
  • 將與其他 Azure 監視器數據交叉參考的數據(Application Insights、其他監視器記錄數據類型、適用於雲端的 Defender、容器深入解析和虛擬機等等)。
Azure 資料總管 Azure 數據總管現已公開推出,是支援 Application Insights Analytics 和 Azure 監視器記錄的數據平臺。 透過以原始形式使用數據平臺,您可以完全彈性(但需要管理的額外負荷)在叢集上(Kubernetes 角色型存取控制 (RBAC)、保留率、架構等等。 Azure 數據總管提供許多 擷取選項,包括 CSV、TSV 和 JSON 檔案。
  • 不會與 Application Insights 或監視記錄下的任何其他數據相互關聯的數據。
  • 需要 Azure 監視器記錄中目前無法使用的進階擷取或處理功能的數據。

下一步