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.

HTTP Veri Toplayıcısı'na genel bakış gösteren ekran görüntüsü.

İ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:

Örnek kayıt 1'in ekran görüntüsü.

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.

Örnek kayıt 2'nin ekran görüntüsü.

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.

Örnek kayıt 3'ün ekran görüntüsü.

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:

Örnek kayıt 4'ün ekran görüntüsü.

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_CLtü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:

  1. Azure portalında Log Analytics çalışma alanınızı bulun.
  2. Aracılar'ı seçin.
  3. Ç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.
  4. 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.
  • Uygulamanız içinde oluşturulan ancak varsayılan veri türlerinden biri (istekler, bağımlılıklar, özel durumlar vb.) aracılığıyla SDK tarafından alınmayan veriler.
  • Application Insights'taki diğer uygulama verileriyle en sık bağıntılı olan veriler.
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.
  • Application Insights içinde izlenen bir uygulama içinde oluşturulmamış veriler.
    Arama ve olgu tabloları, başvuru verileri, önceden toplanmış istatistikler gibi örnekler verilebilir.
  • Diğer Azure İzleyici verilerine (Application Insights, diğer İzleyici Günlükleri veri türleri, Bulut için Defender, Kapsayıcı içgörüleri ve sanal makineler vb.) karşı çapraz başvuru yapılacak veriler.
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.
  • Application Insights veya İzleyici Günlükleri altındaki diğer verilerle ilişkilendirilmeyecek veriler.
  • Azure İzleyici Günlükleri'nde bugün mevcut olmayan gelişmiş alma veya işleme özellikleri gerektiren veriler.

Sonraki adımlar