使用 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。 當您提交數據時,系統會在存放庫中為要求承載中的每個記錄建立個別記錄。
建立要求
若要使用 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 的記錄:
如果您要提交下一個專案,且所有格式化為字串的值,則屬性不會變更。 您可以將值轉換成現有的資料類型。
但是,如果您接著進行下一次提交,Azure 監視器會建立新的屬性 boolean_d 和 string_d 。 您無法轉換這些值。
如果您接著提交下列專案,在建立記錄類型之前,Azure 監視器會建立具有三個屬性、 number_s 、 boolean_s 和 string_s的 記錄。 在此專案中,每個初始值都會格式化為字串:
保留的屬性
下列屬性是保留的,不應用於自訂記錄類型。 如果您的承載包含下列任何屬性名稱,您會收到錯誤:
- 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。
針對每個範例,執行下列動作來設定授權標頭的變數:
- 在 Azure 入口網站 中,找出您的Log Analytics工作區。
- 選取 [ 代理程式]。
- 在工作區標識碼右側,選取 [複製] 圖示,然後將標識碼貼上為 [客戶標識符] 變數的值。
- 在 [主要金鑰] 右側,選取 [複製] 圖示,然後將標識碼貼上為共用金鑰變數的值。
或者,您可以變更記錄類型和 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 進行檢測,可讓您透過自定義事件傳送自定義數據。 |
|
Azure 監視器記錄中的數據收集器 API | Azure 監視器記錄中的數據收集器 API 是內嵌數據的完全開放方式。 JSON 物件中格式化的任何數據都可以在這裡傳送。 傳送之後,它會在監視記錄中進行處理並可供使用,以便與監視記錄中的其他數據或其他 Application Insights 數據相互關聯。 將數據當作檔案上傳至 Azure Blob 儲存體 Blob 相當容易,其中會處理檔案,然後上傳至 Log Analytics。 如需範例實作,請參閱 使用數據收集器 API 建立數據管線。 |
|
Azure 資料總管 | Azure 數據總管現已公開推出,是支援 Application Insights Analytics 和 Azure 監視器記錄的數據平臺。 透過以原始形式使用數據平臺,您可以完全彈性(但需要管理的額外負荷)在叢集上(Kubernetes 角色型存取控制 (RBAC)、保留率、架構等等。 Azure 數據總管提供許多 擷取選項,包括 CSV、TSV 和 JSON 檔案。 |
|
下一步
使用記錄搜尋 API 從 Log Analytics 工作區擷取數據。
深入瞭解如何使用 Logic Apps工作流程對 Azure 監視器使用資料收集器 API 建立數據管線。