Wysyłanie danych dziennika do usługi Azure Monitor przy użyciu interfejsu API modułu zbierającego dane HTTP (przestarzałe)

W tym artykule pokazano, jak używać interfejsu API modułu zbierającego dane HTTP do wysyłania danych dzienników do usługi Azure Monitor z poziomu klienta interfejsu API REST. W tym artykule opisano sposób formatowania danych zbieranych przez skrypt lub aplikację, dołączania ich do żądania i żądania autoryzowanego przez usługę Azure Monitor. Udostępniamy przykłady dla programu Azure PowerShell, języka C# i języka Python.

Uwaga

Interfejs API modułu zbierającego dane HTTP usługi Azure Monitor został przestarzały i nie będzie już działać od 14.09.2026 r. Został on zastąpiony przez interfejs API pozyskiwania dzienników.

Pojęcia

Interfejs API modułu zbierającego dane HTTP umożliwia wysyłanie danych dziennika do obszaru roboczego usługi Log Analytics w usłudze Azure Monitor z dowolnego klienta, który może wywoływać interfejs API REST. Klient może być elementem Runbook w usłudze Azure Automation, który zbiera dane zarządzania z platformy Azure lub innej chmury, lub może być alternatywnym systemem zarządzania, który używa usługi Azure Monitor do konsolidacji i analizowania danych dzienników.

Wszystkie dane w obszarze roboczym usługi Log Analytics są przechowywane jako rekord o określonym typie rekordu. Dane można sformatować w celu wysłania do interfejsu API modułu zbierającego dane HTTP jako wielu rekordów w formacie JavaScript Object Notation (JSON). Podczas przesyłania danych pojedynczy rekord jest tworzony w repozytorium dla każdego rekordu w ładunku żądania.

Screenshot illustrating the HTTP Data Collector overview.

Utwórz żądanie

Aby użyć interfejsu API modułu zbierającego dane HTTP, należy utworzyć żądanie POST zawierające dane do wysłania w formacie JSON. Następne trzy tabele zawierają listę atrybutów wymaganych dla każdego żądania. Bardziej szczegółowo opisujemy każdy atrybut w dalszej części artykułu.

Identyfikator URI żądania

Atrybut Właściwości
Method POST
Identyfikator URI <https:// CustomerId.ods.opinsights.azure.com/api/logs?api-version=2016-04-01>
Typ zawartości application/json

Parametry identyfikatora URI żądania

Parametr Opis
CustomerID (Identyfikator klienta) Unikatowy identyfikator obszaru roboczego usługi Log Analytics.
Zasób Nazwa zasobu interfejsu API: /api/logs.
Wersja interfejsu API Wersja interfejsu API do użycia z tym żądaniem. Obecnie wersja to 2016-04-01.

Nagłówki żądań

Nagłówek opis
Autoryzacja Podpis autoryzacji. W dalszej części artykułu możesz dowiedzieć się, jak utworzyć nagłówek HMAC-SHA256.
Typ dziennika Określ typ rekordu przesyłanych danych. Może zawierać tylko litery, cyfry i znak podkreślenia (_) i nie może przekraczać 100 znaków.
x-ms-date Data przetworzenia żądania w formacie RFC 1123 .
x-ms-AzureResourceId Identyfikator zasobu platformy Azure, z którymi powinny być skojarzone dane. Wypełnia właściwość _ResourceId i umożliwia uwzględnianie danych w zapytaniach kontekstowych zasobów. Jeśli to pole nie zostanie określone, dane nie zostaną uwzględnione w zapytaniach kontekstowych zasobów.
pole wygenerowane przez czas Nazwa pola w danych, które zawiera znacznik czasu elementu danych. Jeśli określisz pole, jego zawartość jest używana dla elementu TimeGenerated. Jeśli to pole nie zostanie określone, wartością domyślną dla właściwości TimeGenerated jest czas pozyskiwania komunikatu. Zawartość pola komunikatu powinna być zgodna z formatem ISO 8601 RRRR-MM-DDThh:mm:ssZ. Wartość Wygenerowana czas nie może być starsza niż 2 dni przed odebraniem czasu lub więcej niż dzień w przyszłości. W takim przypadku czas pozyskiwania komunikatu będzie używany.

Autoryzacja

Każde żądanie do interfejsu API modułu zbierającego dane HTTP usługi Azure Monitor musi zawierać nagłówek autoryzacji. Aby uwierzytelnić żądanie, należy podpisać żądanie przy użyciu klucza podstawowego lub pomocniczego dla obszaru roboczego wysyłającego żądanie. Następnie przekaż ten podpis w ramach żądania.

Oto format nagłówka autoryzacji:

Authorization: SharedKey <WorkspaceID>:<Signature>

WorkspaceID to unikatowy identyfikator obszaru roboczego usługi Log Analytics. Signature to oparty na skrótach kod uwierzytelniania komunikatów (HMAC), który jest konstruowany z żądania, a następnie obliczany przy użyciu algorytmu SHA256. Następnie kodujesz go przy użyciu kodowania Base64.

Użyj tego formatu, aby zakodować ciąg podpisu SharedKey :

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

Oto przykład ciągu podpisu:

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

Jeśli masz ciąg podpisu, zakoduj go przy użyciu algorytmu HMAC-SHA256 w ciągu zakodowanym w formacie UTF-8, a następnie zakoduj wynik jako Base64. Użyj tego formatu:

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

Przykłady w następnych sekcjach zawierają przykładowy kod, który ułatwia utworzenie nagłówka autoryzacji.

Treść żądania

Treść komunikatu musi znajdować się w formacie JSON. Musi zawierać co najmniej jeden rekord z nazwą właściwości i parami wartości w następującym formacie. Nazwa właściwości może zawierać tylko litery, cyfry i znak podkreślenia (_).

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

W jednym żądaniu można wsadować wiele rekordów, używając następującego formatu. Wszystkie rekordy muszą być tego samego typu rekordu.

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

Typ i właściwości rekordu

Typ rekordu niestandardowego definiuje się podczas przesyłania danych za pośrednictwem interfejsu API modułu zbierającego dane HTTP usługi Azure Monitor. Obecnie nie można zapisywać danych w istniejących typach rekordów utworzonych przez inne typy danych i rozwiązania. Usługa Azure Monitor odczytuje dane przychodzące, a następnie tworzy właściwości pasujące do typów danych wprowadzonych wartości.

Każde żądanie do interfejsu API modułu zbierającego dane musi zawierać nagłówek Typ dziennika z nazwą typu rekordu. Sufiks _CL jest automatycznie dołączany do wprowadzonej nazwy w celu odróżnienia go od innych typów dzienników jako dziennika niestandardowego. Jeśli na przykład wprowadzisz nazwę MyNewRecordType, usługa Azure Monitor utworzy rekord o typie MyNewRecordType_CL. Dzięki temu nie ma konfliktów między nazwami typów utworzonymi przez użytkownika i dostarczanymi w bieżących lub przyszłych rozwiązaniach firmy Microsoft.

Aby zidentyfikować typ danych właściwości, usługa Azure Monitor dodaje sufiks do nazwy właściwości. Jeśli właściwość zawiera wartość null, właściwość nie jest uwzględniona w tym rekordzie. W tej tabeli wymieniono typ danych właściwości i odpowiadający mu sufiks:

Typ danych właściwości Sufiks
Ciąg _S
Wartość logiczna _B
Liczba rzeczywista _D
Data/godzina _T
Identyfikator GUID (przechowywany jako ciąg) _G

Uwaga

Wartości ciągów, które wydają się być identyfikatorami GUID, otrzymują sufiks _g i sformatowane jako identyfikator GUID, nawet jeśli wartość przychodząca nie zawiera kreski. Na przykład: zarówno "8145d822-13a7-44ad-859c-36f31a84f6dd" i "8145d82213a744ad8 59c36f31a84f6dd" są przechowywane jako "8145d822-13a7-44ad-859c-36f31a84f6dd". Jedyną różnicą między tym i innym ciągiem są _g w nazwie i wstawienie kreski, jeśli nie są podane w danych wejściowych.

Typ danych używany przez usługę Azure Monitor dla każdej właściwości zależy od tego, czy typ rekordu dla nowego rekordu już istnieje.

  • Jeśli typ rekordu nie istnieje, usługa Azure Monitor tworzy nowy przy użyciu wnioskowania typu JSON w celu określenia typu danych dla każdej właściwości dla nowego rekordu.
  • Jeśli typ rekordu istnieje, usługa Azure Monitor próbuje utworzyć nowy rekord na podstawie istniejących właściwości. Jeśli typ danych właściwości w nowym rekordzie nie jest zgodny i nie można go przekonwertować na istniejący typ lub jeśli rekord zawiera właściwość, która nie istnieje, usługa Azure Monitor tworzy nową właściwość, która ma odpowiedni sufiks.

Na przykład następujący wpis przesyłania tworzy rekord z trzema właściwościami, number_d, boolean_b i string_s:

Screenshot of sample record 1.

Jeśli chcesz przesłać ten następny wpis, ze wszystkimi wartościami sformatowanymi jako ciągi, właściwości nie zostaną zmienione. Możesz przekonwertować wartości na istniejące typy danych.

Screenshot of sample record 2.

Jeśli jednak nastąpi następne przesłanie, usługa Azure Monitor utworzy nowe właściwości boolean_d i string_d. Nie można przekonwertować tych wartości.

Screenshot of sample record 3.

Jeśli następnie prześlesz następujący wpis, przed utworzeniem typu rekordu usługa Azure Monitor utworzy rekord z trzema właściwościami, number_s, boolean_s i string_s. W tym wpisie każda z wartości początkowych jest formatowana jako ciąg:

Screenshot of sample record 4.

Właściwości zarezerwowane

Następujące właściwości są zarezerwowane i nie powinny być używane w niestandardowym typie rekordu. Jeśli ładunek zawiera dowolną z tych nazw właściwości, zostanie wyświetlony błąd:

  • tenant
  • TimeGenerated
  • RawData

Limity danych

Dane publikowane w interfejsie API zbierania danych usługi Azure Monitor podlegają pewnym ograniczeniom:

  • Maksymalnie 30 MB na post do interfejsu API modułu zbierającego dane usługi Azure Monitor. Jest to limit rozmiaru pojedynczego wpisu. Jeśli dane z pojedynczego wpisu przekraczają 30 MB, należy podzielić dane na fragmenty o mniejszym rozmiarze i wysłać je współbieżnie.
  • Maksymalnie 32 KB dla wartości pól. Jeśli wartość pola jest większa niż 32 KB, dane zostaną obcięte.
  • Zalecane maksymalnie 50 pól dla danego typu. Jest to praktyczny limit z perspektywy użyteczności i środowiska wyszukiwania.
  • Tabele w obszarach roboczych usługi Log Analytics obsługują tylko 500 kolumn (nazywanych polami w tym artykule).
  • Maksymalnie 45 znaków dla nazw kolumn.

Kody powrotne

Kod stanu HTTP 200 oznacza, że żądanie zostało odebrane do przetworzenia. Oznacza to, że operacja zakończyła się pomyślnie.

Pełny zestaw kodów stanu, które może zwrócić usługa, znajduje się w poniższej tabeli:

Kod Status Kod błędu opis
200 OK Żądanie zostało pomyślnie zaakceptowane.
400 Nieprawidłowe żądanie NieaktywnyCustomer Obszar roboczy został zamknięty.
400 Nieprawidłowe żądanie InvalidApiVersion Określona wersja interfejsu API nie została rozpoznana przez usługę.
400 Nieprawidłowe żądanie InvalidCustomerId Określony identyfikator obszaru roboczego jest nieprawidłowy.
400 Nieprawidłowe żądanie InvalidDataFormat Przesłano nieprawidłowy kod JSON. Treść odpowiedzi może zawierać więcej informacji na temat sposobu rozwiązywania błędu.
400 Nieprawidłowe żądanie InvalidLogType Określony typ dziennika zawiera znaki specjalne lub cyfry.
400 Nieprawidłowe żądanie MissingApiVersion Nie określono wersji interfejsu API.
400 Nieprawidłowe żądanie MissingContentType Nie określono typu zawartości.
400 Nieprawidłowe żądanie MissingLogType Nie określono wymaganego typu dziennika wartości.
400 Nieprawidłowe żądanie NieobsługiwanycontentType Typ zawartości nie został ustawiony na wartość application/json.
403 Dostęp zabroniony Nieprawidłowa autoryzacja Usługa nie może uwierzytelnić żądania. Sprawdź, czy identyfikator obszaru roboczego i klucz połączenia są prawidłowe.
404 Nie znaleziono Podany adres URL jest niepoprawny lub żądanie jest zbyt duże.
429 Zbyt wiele żądań W usłudze występuje duża ilość danych z twojego konta. Ponów próbę żądania później.
500 Wewnętrzny błąd serwera Nieokreślony błąd Usługa napotkała błąd wewnętrzny. Ponów próbę żądania.
503 Usługa niedostępna ServiceUnavailable Usługa jest obecnie niedostępna do odbierania żądań. Ponów próbę żądania.

Zapytania o dane

Aby wykonać zapytanie dotyczące danych przesyłanych przez interfejs API modułu zbierającego dane HTTP usługi Azure Monitor, wyszukaj rekordy, których typ jest równy określonej wartości LogType i dołączono je _CL. Jeśli na przykład użyto elementu MyCustomLog, zwracasz wszystkie rekordy za pomocą polecenia MyCustomLog_CL.

Przykładowe żądania

W tej sekcji przedstawiono przykłady pokazujące sposób przesyłania danych do interfejsu API modułu zbierającego dane HTTP usługi Azure Monitor przy użyciu różnych języków programowania.

Dla każdego przykładu ustaw zmienne nagłówka autoryzacji, wykonując następujące czynności:

  1. W witrynie Azure Portal znajdź obszar roboczy usługi Log Analytics.
  2. Wybierz pozycję Agenci.
  3. Po prawej stronie identyfikatora obszaru roboczego wybierz ikonę Kopiuj, a następnie wklej identyfikator jako wartość zmiennej Identyfikator klienta.
  4. Po prawej stronie pozycji Klucz podstawowy wybierz ikonę Kopiuj , a następnie wklej identyfikator jako wartość zmiennej Klucz wspólny.

Alternatywnie można zmienić zmienne dla typu dziennika i danych 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  

Alternatywy i zagadnienia

Mimo że interfejs API modułu zbierającego dane powinien obejmować większość Twoich potrzeb w miarę zbierania danych w dziennikach platformy Azure, możesz wymagać alternatywnego podejścia do rozwiązania niektórych ograniczeń interfejsu API. Opcje, w tym główne zagadnienia, są wymienione w poniższej tabeli:

Alternatywne rozwiązanie opis Najlepiej nadaje się do
Zdarzenia niestandardowe: pozyskiwanie natywnych zestawów SDK w usłudze Application Szczegółowe informacje Aplikacja Szczegółowe informacje, zwykle instrumentowana za pomocą zestawu SDK w aplikacji, umożliwia wysyłanie danych niestandardowych za pośrednictwem zdarzeń niestandardowych.
  • Dane wygenerowane w aplikacji, ale nie są pobierane przez zestaw SDK za pomocą jednego z domyślnych typów danych (żądań, zależności, wyjątków itd.).
  • Dane, które są najczęściej skorelowane z innymi danymi aplikacji w usłudze Application Szczegółowe informacje.
Interfejs API modułu zbierającego dane w dziennikach usługi Azure Monitor Interfejs API modułu zbierającego dane w dziennikach usługi Azure Monitor to całkowicie otwarty sposób pozyskiwania danych. Wszystkie dane sformatowane w obiekcie JSON można wysłać tutaj. Po wysłaniu jest ona przetwarzana i udostępniana w dziennikach monitorowania, które mają być skorelowane z innymi danymi w dziennikach monitorowania lub względem innych danych usługi Application Szczegółowe informacje.

Dość łatwo jest przekazać dane jako pliki do obiektu blob usługi Azure Blob Storage, w którym pliki zostaną przetworzone, a następnie przekazane do usługi Log Analytics. Aby zapoznać się z przykładową implementacją, zobacz Tworzenie potoku danych przy użyciu interfejsu API modułu zbierającego dane.
  • Dane, które nie muszą być generowane w aplikacji instrumentowanej w ramach Szczegółowe informacje aplikacji.
    Przykłady obejmują tabele odnośników i faktów, dane referencyjne, wstępnie zagregowane statystyki itd.
  • Dane, które będą odsyłane do innych danych usługi Azure Monitor (aplikacja Szczegółowe informacje, inne typy danych dzienników monitorowania, Defender dla Chmury, szczegółowe informacje o kontenerach i maszynach wirtualnych itd.).
Azure Data Explorer Usługa Azure Data Explorer, teraz ogólnie dostępna dla publicznej wersji, to platforma danych, która obsługuje dzienniki usługi Application Szczegółowe informacje Analytics i Azure Monitor. Korzystając z platformy danych w postaci pierwotnej, masz pełną elastyczność (ale wymagasz nakładu pracy związanego z zarządzaniem) w klastrze (kontrola dostępu oparta na rolach Kubernetes), szybkość przechowywania, schemat itd. Usługa Azure Data Explorer udostępnia wiele opcji pozyskiwania, w tym pliki CSV, TSV i JSON .
  • Dane, które nie będą skorelowane z żadnymi innymi danymi w obszarze Application Szczegółowe informacje lub Monitor Logs.
  • Dane, które wymagają zaawansowanych możliwości pozyskiwania lub przetwarzania, które nie są obecnie dostępne w dziennikach usługi Azure Monitor.

Następne kroki