HTTP Veri Toplayıcı API'sini kullanarak Azure İzleyici'ye günlük verileri gönderme (kullanım dışı)
Bu makalede, BIR REST API istemcisinden Azure İzleyici'ye günlük verileri göndermek için HTTP Veri Toplayıcı API'sinin nasıl kullanılacağı gösterilmektedir. Betiğiniz veya uygulamanız tarafından toplanan verilerin nasıl biçimlendirildiğini, bir isteğe nasıl ekleneceğini ve bu isteğin Azure İzleyici tarafından nasıl yetkilendirildiğini açıklar. Azure PowerShell, C# ve Python için örnekler sunuyoruz.
Not
Azure İzleyici HTTP Veri Toplayıcı API'si kullanımdan kaldırılmıştır ve 14.09.2026 itibarıyla artık işlevsel olmayacaktır. Günlük alımı API'siyle değiştirildi.
Kavramlar
REST API çağırabilen herhangi bir istemciden Azure İzleyici'deki log analytics çalışma alanına günlük verileri göndermek için HTTP Veri Toplayıcı API'sini kullanabilirsiniz. İstemci, Azure Otomasyonu'da Azure'dan veya başka bir buluttan yönetim verileri toplayan bir runbook veya günlük verilerini birleştirmek ve analiz etmek için Azure İzleyici'yi kullanan alternatif bir yönetim sistemi olabilir.
Log Analytics çalışma alanı içindeki tüm veriler, belirli bir kayıt türüne sahip bir kayıt olarak depolanır. Verilerinizi, HTTP Veri Toplayıcı API'sine JavaScript Nesne Gösterimi'nde (JSON) birden çok kayıt olarak gönderecek şekilde biçimlendirebilirsiniz. Verileri gönderdiğinizde, istek yükündeki her kayıt için depoda tek bir kayıt oluşturulur.
İstek oluşturma
HTTP Veri Toplayıcı API'sini kullanmak için JSON'da gönderilecek verileri içeren bir POST isteği oluşturursunuz. Sonraki üç tabloda her istek için gereken öznitelikler listelenir. Makalenin devamında her özniteliği daha ayrıntılı olarak açıklıyoruz.
İstek URI'si
Öznitelik | Özellik |
---|---|
Metot | POST |
URI | <https:// CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01> |
İçerik türü | application/json |
İstek URI parametreleri
Parametre | Açıklama |
---|---|
CustomerID | Log Analytics çalışma alanının benzersiz tanımlayıcısı. |
Kaynak | API kaynak adı: /api/logs. |
API Sürümü | Bu istekle kullanılacak API sürümü. Şu anda sürüm 2016-04-01'dir. |
İstek üst bilgileri
Üst bilgi | Açıklama |
---|---|
Yetkilendirme | Yetkilendirme imzası. Makalenin ilerleyen bölümlerinde HMAC-SHA256 üst bilgisi oluşturma hakkında bilgi edinebilirsiniz. |
Günlük Türü | Gönderilen verilerin kayıt türünü belirtin. Yalnızca harf, sayı ve alt çizgi (_) karakteri içerebilir ve 100 karakteri aşamaz. |
x-ms-date | İsteğin rfc 1123 biçiminde işlendiği tarih. |
x-ms-AzureResourceId | Verilerin ilişkilendirilmesi gereken Azure kaynağının kaynak kimliği. _ResourceId özelliğini doldurur ve verilerin kaynak bağlamı sorgularına eklenmesine izin verir. Bu alan belirtilmezse, veriler kaynak bağlamı sorgularında yer almayacaktır. |
zaman tarafından oluşturulan alan | Veri öğesi zaman damgasını içeren verilerdeki bir alanın adı. Bir alan belirtirseniz, içindekiler TimeGenerated için kullanılır. Bu alanı belirtmezseniz, TimeGenerated için varsayılan değer iletinin alınıp alınmadığını gösterir. İleti alanının içeriği ISO 8601 biçiminde YYYY-AA-GGThh:mm:ssZ olmalıdır. Oluşturulan Zaman değeri, alınan süreden 2 gün önce veya gelecekte bir günden daha eski olamaz. Böyle bir durumda, iletinin alınacağı süre kullanılır. |
Yetkilendirme
Azure İzleyici HTTP Veri Toplayıcı API'sine yönelik tüm istekler bir yetkilendirme üst bilgisi içermelidir. Bir isteğin kimliğini doğrulamak için isteği, isteği yapan çalışma alanının birincil veya ikincil anahtarıyla imzalayın. Ardından, isteğin bir parçası olarak bu imzayı geçirin.
Yetkilendirme üst bilgisinin biçimi aşağıdadır:
Authorization: SharedKey <WorkspaceID>:<Signature>
WorkspaceID , Log Analytics çalışma alanının benzersiz tanımlayıcısıdır. İmza, istekten üretilen ve ardından SHA256 algoritması kullanılarak hesaplanan Karma Tabanlı İleti Kimlik Doğrulama Kodudur (HMAC). Ardından Base64 kodlamasını kullanarak kodlarsınız.
SharedKey imza dizesini kodlamak için şu biçimi kullanın:
StringToSign = VERB + "\n" +
Content-Length + "\n" +
Content-Type + "\n" +
"x-ms-date:" + x-ms-date + "\n" +
"/api/logs";
aşağıda bir imza dizesi örneği verilmişti:
POST\n1024\napplication/json\nx-ms-date:Mon, 04 Apr 2016 08:00:00 GMT\n/api/logs
İmza dizesine sahip olduğunuzda, UTF-8 ile kodlanmış dizede HMAC-SHA256 algoritmasını kullanarak bunu kodlayın ve ardından sonucu Base64 olarak kodlayın. Şu biçimi kullanın:
Signature=Base64(HMAC-SHA256(UTF8(StringToSign)))
Sonraki bölümlerde yer alan örneklerde yetkilendirme üst bilgisi oluşturmanıza yardımcı olacak örnek kodlar bulunur.
Request body
İletinin gövdesi JSON içinde olmalıdır. Özellik adı ve değer çiftleri aşağıdaki biçimde olan bir veya daha fazla kayıt içermelidir. Özellik adı yalnızca harf, sayı ve alt çizgi (_) karakteri içerebilir.
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Aşağıdaki biçimi kullanarak birden çok kaydı tek bir istekte birlikte toplu işleyebilirsiniz. Tüm kayıtlar aynı kayıt türünde olmalıdır.
[
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
},
{
"property 1": "value1",
"property 2": "value2",
"property 3": "value3",
"property 4": "value4"
}
]
Kayıt türü ve özellikleri
Azure İzleyici HTTP Veri Toplayıcı API'sini kullanarak veri gönderirken özel bir kayıt türü tanımlarsınız. Şu anda, diğer veri türleri ve çözümleri tarafından oluşturulan mevcut kayıt türlerine veri yazamazsınız. Azure İzleyici gelen verileri okur ve ardından girdiğiniz değerlerin veri türleriyle eşleşen özellikler oluşturur.
Veri Toplayıcı API'sine yapılan her istek, kayıt türünün adına sahip bir Günlük Türü üst bilgisi içermelidir. _CL soneki, özel günlük olarak diğer günlük türlerinden ayırmak için girdiğiniz ada otomatik olarak eklenir. Örneğin, MyNewRecordType adını girerseniz Azure İzleyici MyNewRecordType_CL türünde bir kayıt oluşturur. Bu, kullanıcı tarafından oluşturulan tür adları ile geçerli veya gelecekteki Microsoft çözümlerinde gönderilen adlar arasında çakışma olmamasını sağlamaya yardımcı olur.
Bir özelliğin veri türünü tanımlamak için Azure İzleyici özellik adına bir sonek ekler. Bir özellik null değer içeriyorsa, özellik bu kayda dahil değildir. Bu tabloda özellik veri türü ve buna karşılık gelen sonek listelenir:
Özellik veri türü | Sonek |
---|---|
String | _s |
Boolean | _b |
Çift | _d |
Tarih/saat | _t |
GUID (dize olarak depolanır) | _g |
Not
GUID olarak görünen dize değerlerine _g soneki verilir ve gelen değer tire içermese bile GUID olarak biçimlendirilir. Örneğin, "8145d822-13a7-44ad-859c-36f31a84f6dd" ve "8145d82213a744ad"859c36f31a84f6dd" "8145d822-13a7-44ad-859c-36f31a84f6dd" olarak depolanır. Bu ve başka bir dize arasındaki tek fark, addaki _g ve girişte sağlanmamışsa tirelerin eklenmesidir.
Azure İzleyici'nin her özellik için kullandığı veri türü, yeni kaydın kayıt türünün zaten var olup olmadığına bağlıdır.
- Kayıt türü yoksa Azure İzleyici, yeni kayıt için her özelliğin veri türünü belirlemek üzere JSON türü çıkarımı kullanarak yeni bir tane oluşturur.
- Kayıt türü mevcutsa, Azure İzleyici mevcut özelliklere göre yeni bir kayıt oluşturmayı dener. Yeni kayıttaki bir özelliğin veri türü eşleşmiyorsa ve var olan türe dönüştürülemiyorsa veya kayıt mevcut olmayan bir özellik içeriyorsa, Azure İzleyici ilgili son eke sahip yeni bir özellik oluşturur.
Örneğin, aşağıdaki gönderim girdisi number_d, boolean_b ve string_s olmak üzere üç özelliğe sahip bir kayıt oluşturur:
Bu sonraki girdiyi, tüm değerler dize olarak biçimlendirilmiş şekilde gönderirseniz, özellikler değişmez. Değerleri mevcut veri türlerine dönüştürebilirsiniz.
Ancak bu sonraki gönderimi yaparsanız Azure İzleyici yeni özellikleri boolean_d ve string_d oluşturur. Bu değerleri dönüştüremezsiniz.
Daha sonra aşağıdaki girdiyi gönderirseniz, kayıt türü oluşturulmadan önce Azure İzleyici number_s, boolean_s ve string_s olmak üzere üç özelliğe sahip bir kayıt oluşturur. Bu girdide, ilk değerlerin her biri bir dize olarak biçimlendirilir:
Ayrılmış özellikler
Aşağıdaki özellikler ayrılmıştır ve özel kayıt türünde kullanılmamalıdır. Yükünüz şu özellik adlarından herhangi birini içeriyorsa bir hata alırsınız:
- tenant
- TimeGenerated
- RawData
Veri sınırları
Azure İzleyici Veri toplama API'sine gönderilen veriler belirli kısıtlamalara tabidir:
- Azure İzleyici Veri Toplayıcı API'sine gönderi başına en fazla 30 MB. Bu, tek bir gönderi için boyut sınırıdır. Tek bir gönderideki veriler 30 MB'ı aşarsa, verileri daha küçük boyutlu öbeklere bölmeniz ve bunları eşzamanlı olarak göndermeniz gerekir.
- Alan değerleri için en fazla 32 KB. Alan değeri 32 KB'ı aşıyorsa veriler kesilir.
- Belirli bir tür için en fazla 50 alan önerilir. Bu, kullanılabilirlik ve arama deneyimi açılarından belirlenmiş bir limittir.
- Log Analytics çalışma alanlarındaki tablolar yalnızca en fazla 500 sütunu destekler (bu makalede alanlar olarak adlandırılır).
- Sütun adları için en fazla 45 karakter.
Dönüş kodları
HTTP durum kodu 200, isteğin işlenmek üzere alındığı anlamına gelir. Bu, işlemin başarıyla tamamlandığını gösterir.
Hizmetin döndürebileceği durum kodlarının tamamı aşağıdaki tabloda listelenmiştir:
Kod | Durum | Hata kodu | Açıklama |
---|---|---|---|
200 | Tamam | İstek başarıyla kabul edildi. | |
400 | Hatalı istek | InactiveCustomer | Çalışma alanı kapatıldı. |
400 | Hatalı istek | InvalidApiVersion | Belirttiğiniz API sürümü hizmet tarafından tanınmadı. |
400 | Hatalı istek | InvalidCustomerId | Belirtilen çalışma alanı kimliği geçersiz. |
400 | Hatalı istek | InvalidDataFormat | Geçersiz bir JSON gönderildi. Yanıt gövdesi, hatayı düzeltme hakkında daha fazla bilgi içerebilir. |
400 | Hatalı istek | InvalidLogType | Belirtilen günlük türü özel karakterler veya sayısal karakterler içeriyordu. |
400 | Hatalı istek | MissingApiVersion | API sürümü belirtilmedi. |
400 | Hatalı istek | MissingContentType | İçerik türü belirtilmedi. |
400 | Hatalı istek | MissingLogType | Gerekli değer günlük türü belirtilmedi. |
400 | Hatalı istek | UnsupportedContentType | İçerik türü application/json olarak ayarlanmadı. |
403 | Yasak | InvalidAuthorization | Hizmet isteğin kimliğini doğrulayamadı. Çalışma alanı kimliğinin ve bağlantı anahtarının geçerli olduğunu doğrulayın. |
404 | Bulunamadı | Sağlanan URL yanlış veya istek çok büyük. | |
429 | Çok Fazla İstek Var | Hizmet, hesabınızdan yüksek miktarda veriyle karşılaşıyor. Lütfen isteği daha sonra yeniden deneyin. | |
500 | İç Sunucu Hatası | UnspecifiedError | Hizmet bir iç hatayla karşılaştı. Lütfen isteği yeniden deneyin. |
503 | Hizmet Kullanılamıyor | ServiceUnavailable | Hizmet şu anda istekleri almak için kullanılamıyor. Lütfen isteğinizi yeniden deneyin. |
Verileri sorgulama
Azure İzleyici HTTP Veri Toplayıcı API'sinin gönderdiği verileri sorgulamak için Türü belirttiğiniz ve _CL ile eklediğiniz LogType değerine eşit kayıtları arayın. Örneğin, MyCustomLog kullandıysanız, ile MyCustomLog_CL
tüm kayıtları döndürebilirsiniz.
Örnek istekler
Bu bölümde, çeşitli programlama dillerini kullanarak Azure İzleyici HTTP Veri Toplayıcı API'sine veri göndermeyi gösteren örnekler verilmiştir.
Her örnek için aşağıdakileri yaparak yetkilendirme üst bilgisinin değişkenlerini ayarlayın:
- Azure portalında Log Analytics çalışma alanınızı bulun.
- Aracılar'ı seçin.
- Çalışma Alanı Kimliği'nin sağındaki Kopyala simgesini seçin ve ardından Kimliği Müşteri Kimliği değişkeninin değeri olarak yapıştırın.
- Birincil Anahtar'ın sağındaki Kopyala simgesini seçin ve kimliği Paylaşılan Anahtar değişkeninin değeri olarak yapıştırın.
Alternatif olarak, günlük türü ve JSON verilerinin değişkenlerini değiştirebilirsiniz.
# 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
Alternatifler ve dikkat edilmesi gerekenler
Azure Günlükleri'ne serbest biçimli veriler toplarken Veri Toplayıcı API'si gereksinimlerinizin çoğunu karşılamalıdır ancak API'nin bazı sınırlamalarını aşmak için alternatif bir yaklaşıma ihtiyacınız olabilir. Önemli noktalar da dahil olmak üzere seçenekleriniz aşağıdaki tabloda listelenmiştir:
Alternatif | Açıklama | En uygun |
---|---|---|
Özel olaylar: Application Insights'ta yerel SDK tabanlı alım | Genellikle uygulamanızdaki bir SDK aracılığıyla izlenen Application Insights, Özel Olaylar aracılığıyla özel veri göndermenizi sağlar. |
|
Azure İzleyici Günlüklerinde Veri Toplayıcı API'si | Azure İzleyici Günlüklerindeki Veri Toplayıcı API'si, verileri almak için tamamen açık uçlu bir yöntemdir. JSON nesnesinde biçimlendirilmiş tüm veriler buraya gönderilebilir. Gönderildikten sonra, İzleyici Günlükleri'nde, İzleme Günlükleri'ndeki diğer verilerle veya diğer Application Insights verileriyle bağıntılı olacak şekilde işlenir ve kullanılabilir hale getirilir. Verileri dosya olarak bir Azure Blob Depolama bloba yüklemek oldukça kolaydır; burada dosyalar işlenir ve ardından Log Analytics'e yüklenir. Örnek uygulama için bkz . Veri Toplayıcı API'siyle veri işlem hattı oluşturma. |
|
Azure Veri Gezgini | Genel kullanıma sunulan Azure Veri Gezgini, Application Insights Analytics ve Azure İzleyici Günlüklerini destekleyen veri platformudur. Veri platformunu ham biçiminde kullanarak küme (Kubernetes rol tabanlı erişim denetimi (RBAC), bekletme oranı, şema vb. üzerinde tam esnekliğe sahip olursunuz (ancak yönetim yükü gerektirir). Azure Veri Gezgini CSV, TSV ve JSON dosyaları dahil olmak üzere birçok alım seçeneği sunar. |
|
Sonraki adımlar
Log Analytics çalışma alanından veri almak için Log Search API'sini kullanın.
Azure İzleyici'ye Logic Apps iş akışı kullanarak Veri Toplayıcı API'siyle veri işlem hattı oluşturma hakkında daha fazla bilgi edinin.