使用 HTTP 資料收集器 API 將記錄資料傳送至 Azure 監視器 (已淘汰)
本文示範如何使用 HTTP 資料收集器 API 將記錄資料從 REST API 用戶端傳送給 Azure 監視器。 內容說明如何將指令碼或應用程式收集的資料格式化、將資料包含在要求中,以及讓 Azure 監視器授權該要求。 我們提供 Azure PowerShell、C# 和 Python 的範例。
注意
Azure 監視器 HTTP 資料收集器 API 已淘汰,且自 2026 年 9 月 14 日起將不再運作。 它已由記錄擷取 API 取代。
概念
您可以在 Azure 監視器中使用 HTTP 資料收集器 API,將記錄資料從任何可呼叫 REST API 的用戶端傳送至 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 標頭。 |
Log-Type | 指定要提交的資料記錄類型。 只能包含字母、數字和底線 (_) 字元,且不能超過 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 工作區的唯一識別碼。 Signature 是雜湊式訊息驗證碼 (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
如果您有此簽章字串,請使用 HMAC-SHA256 演算法在 UTF-8 編碼的字串上進行編碼,然後將結果編碼為 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 |
Double | _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 的資料受特定條件所限制:
- 可張貼至 Azure 監視器資料收集器 API 的每個張貼項目大小上限為 30 MB。 這是單一張貼項目的大小限制。 如果來自單一張貼項目的資料超出 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 提交的資料,請搜尋 Type 等於您指定的 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 分析和 Azure 監視器記錄的資料平台,現已公開推出。 透過使用原始形式的資料平台,您對於叢集 (Kubernetes 角色型存取控制 (RBAC)、留駐率、結構描述) 擁有完整的彈性 (但需要管理負荷)。 Azure 資料總管提供許多擷取選項,包括 CSV、TSV 和 JSON 檔案。 |
|
下一步
使用記錄搜尋 API 從 Log Analytics 工作區擷取資料。
深入了解如何透過 Azure 監視器的 Logic Apps 工作流程,使用資料收集器 API 建立資料管線。