Interfejs API pozyskiwania dzienników w usłudze Azure Monitor

  • Artykuł

Interfejs API pozyskiwania dzienników w usłudze Azure Monitor umożliwia wysyłanie danych do obszaru roboczego usługi Log Analytics przy użyciu wywołania interfejsu API REST lub bibliotek klienckich. Interfejs API umożliwia wysyłanie danych do obsługiwanych tabel platformy Azure lub do tworzonych tabel niestandardowych. Możesz również rozszerzyć schemat tabel platformy Azure przy użyciu kolumn niestandardowych, aby akceptować dodatkowe dane.

Podstawowa operacja

Dane można wysyłać do interfejsu API pozyskiwania dzienników z dowolnej aplikacji, która może wykonać wywołanie interfejsu API REST. Może to być aplikacja niestandardowa, którą tworzysz, lub może to być aplikacja lub agent, który rozumie, jak wysyłać dane do interfejsu API. Aplikacja wysyła dane do punktu końcowego zbierania danych (DCE), który jest unikatowym punktem połączenia dla subskrypcji platformy Azure. Określa regułę zbierania danych (DCR), która zawiera tabelę docelową i obszar roboczy oraz poświadczenia rejestracji aplikacji z dostępem do określonego kontrolera domeny.

Dane wysyłane przez aplikację do interfejsu API muszą być sformatowane w formacie JSON i zgodne ze strukturą oczekiwaną przez kontroler domeny. Nie musi być zgodna ze strukturą tabeli docelowej, ponieważ kontroler domeny może zawierać przekształcenie w celu przekonwertowania danych w celu dopasowania ich do struktury tabeli. Tabelę docelową i obszar roboczy można zmodyfikować, modyfikując kontroler domeny bez żadnych zmian w wywołaniu interfejsu API lub danych źródłowych.

Diagram przedstawiający przegląd interfejsu API pozyskiwania dzienników.

Konfigurowanie

W poniższej tabeli opisano każdy składnik na platformie Azure, który należy skonfigurować przed użyciem interfejsu API pozyskiwania dzienników.

Uwaga

Aby uzyskać skrypt programu PowerShell, który automatyzuje konfigurację tych składników, zobacz Przykładowy kod służący do wysyłania danych do usługi Azure Monitor przy użyciu interfejsu API pozyskiwania dzienników.

Składnik Function
Rejestracja aplikacji i wpis tajny Rejestracja aplikacji służy do uwierzytelniania wywołania interfejsu API. Należy udzielić mu uprawnień do kontrolera domeny opisanego poniżej. Wywołanie interfejsu API zawiera identyfikator aplikacji (klienta) i identyfikator katalogu (dzierżawy) aplikacji oraz wartość wpisu tajnego aplikacji.

Zobacz Create a Microsoft Entra application and service principal that can access resources (Tworzenie aplikacji entra firmy Microsoft i jednostki usługi, która może uzyskiwać dostęp do zasobów ) i Create a new application secret (Tworzenie nowego wpisu tajnego aplikacji).
Punkt końcowy zbierania danych (DCE) Kontroler domeny zapewnia punkt końcowy dla aplikacji do wysłania. Pojedynczy kontroler domeny może obsługiwać wiele kontrolerów DCE, dzięki czemu możesz użyć istniejącego kontrolera domeny, jeśli masz już jeden w tym samym regionie co obszar roboczy usługi Log Analytics.

Zobacz Tworzenie punktu końcowego zbierania danych.
Tabela w obszarze roboczym usługi Log Analytics Tabela w obszarze roboczym usługi Log Analytics musi istnieć przed wysłaniem do niej danych. Możesz użyć jednej z obsługiwanych tabel platformy Azure lub utworzyć tabelę niestandardową przy użyciu dowolnej z dostępnych metod. Jeśli utworzysz tabelę przy użyciu witryny Azure Portal, zostanie utworzona funkcja DCR, w tym przekształcenie, jeśli jest to wymagane. W przypadku dowolnej innej metody należy ręcznie utworzyć kontroler domeny zgodnie z opisem w następnej sekcji.

Zobacz Tworzenie tabeli niestandardowej.
Reguła zbierania danych (DCR) Usługa Azure Monitor używa reguły zbierania danych (DCR), aby zrozumieć strukturę danych przychodzących i co z nią zrobić. Jeśli struktura tabeli i danych przychodzących nie są zgodne, kontroler domeny może zawierać przekształcenie w celu przekonwertowania danych źródłowych w celu dopasowania ich do tabeli docelowej. Można również użyć przekształcenia do filtrowania danych źródłowych i wykonywania innych obliczeń lub konwersji.

Jeśli tworzysz tabelę niestandardową przy użyciu witryny Azure Portal, kontroler domeny i transformacja zostaną utworzone na podstawie danych przykładowych, które zostały podane. Jeśli używasz istniejącej tabeli lub utworzysz tabelę niestandardową przy użyciu innej metody, musisz ręcznie utworzyć kontroler domeny przy użyciu szczegółów w poniższej sekcji.

Po utworzeniu kontrolera domeny należy udzielić dostępu do niej dla aplikacji utworzonej w pierwszym kroku. W menu Monitor w witrynie Azure Portal wybierz pozycję Reguły zbierania danych, a następnie utworzoną usługę DCR. Wybierz pozycję Kontrola dostępu (IAM) dla kontrolera domeny, a następnie wybierz pozycję Dodaj przypisanie roli, aby dodać rolę Wydawca metryk monitorowania.

Ręczne tworzenie kontrolera domeny

Jeśli wysyłasz dane do tabeli, która już istnieje, musisz ręcznie utworzyć kontroler domeny. Rozpocznij od przykładowego kontrolera DOMENY dla interfejsu API pozyskiwania dzienników i zmodyfikuj następujące parametry w szablonie. Następnie użyj dowolnej metody opisanej w temacie Tworzenie i edytowanie reguł zbierania danych (DCR) w usłudze Azure Monitor , aby utworzyć kontroler domeny.

Parametr Opis
region Region do utworzenia kontrolera domeny. Musi to być zgodne z regionem dcE i obszarem roboczym usługi Log Analytics.
dataCollectionEndpointId Identyfikator zasobu kontrolera domeny.
streamDeclarations Zmień listę kolumn na kolumny w danych przychodzących. Nie musisz zmieniać nazwy strumienia, ponieważ musi być zgodna z streams nazwą w pliku dataFlows.
workspaceResourceId Identyfikator zasobu obszaru roboczego usługi Log Analytics. Nie musisz zmieniać nazwy, ponieważ musi być zgodna z destinations nazwą w pliku dataFlows.
transformKql Zapytanie KQL, które ma zostać zastosowane do danych przychodzących. Jeśli schemat danych przychodzących jest zgodny ze schematem tabeli, można użyć source do przekształcenia, które przekaże dane przychodzące bez zmian. W przeciwnym razie użyj zapytania, które przekształci dane w celu dopasowania ich do schematu tabeli.
outputStream Nazwa tabeli do wysłania danych. W przypadku tabeli niestandardowej dodaj prefiks Custom-table-name><. W przypadku wbudowanej tabeli dodaj prefiks Microsoft-table-name><.

Biblioteki klienta

Oprócz wywołania interfejsu API REST można użyć następujących bibliotek klienckich do wysyłania danych do interfejsu API pozyskiwania dzienników. Biblioteki wymagają tych samych składników opisanych w temacie Konfiguracja. Przykłady użycia każdej z tych bibliotek można znaleźć w temacie Przykładowy kod do wysyłania danych do usługi Azure Monitor przy użyciu interfejsu API pozyskiwania dzienników.

Wywołanie interfejsu API REST

Aby wysłać dane do usługi Azure Monitor za pomocą wywołania interfejsu API REST, wykonaj wywołanie POST za pośrednictwem protokołu HTTP. Szczegółowe informacje wymagane do tego wywołania zostały opisane w tej sekcji.

Identyfikator URI punktu końcowego

Identyfikator URI punktu końcowego używa następującego formatu, w którym identyfikator Data Collection Endpoint DCE i DCR Immutable ID DCR są identyfikowane. Identyfikator niezmienny jest generowany dla kontrolera domeny podczas jego tworzenia. Możesz pobrać go z widoku JSON kontrolera domeny w witrynie Azure Portal. Stream Nameodwołuje się do strumienia w kontrolerze domeny, który powinien obsługiwać dane niestandardowe.

{Data Collection Endpoint URI}/dataCollectionRules/{DCR Immutable ID}/streams/{Stream Name}?api-version=2023-01-01

Na przykład:

https://my-dce-5kyl.eastus-1.ingest.monitor.azure.com/dataCollectionRules/dcr-000a00a000a00000a000000aa000a0aa/streams/Custom-MyTable?api-version=2023-01-01

Nagłówki

W poniższej tabeli opisano nagłówki wywołania interfejsu API.

Nagłówek Wymagany? opis
Autoryzacja Tak Token elementu nośnego uzyskany za pośrednictwem przepływu poświadczeń klienta. Użyj wartości odbiorców tokenu dla chmury:

Chmura publiczna platformy Azure — https://monitor.azure.com
Platforma Microsoft Azure obsługiwana przez chmurę 21Vianet — https://monitor.azure.cn
Chmura platformy Azure dla instytucji rządowych USA — https://monitor.azure.us
Typ zawartości Tak application/json
Content-Encoding Nie. gzip
x-ms-client-request-id Nie. Identyfikator GUID w formacie ciągu. Jest to identyfikator żądania, który może być używany przez firmę Microsoft do celów rozwiązywania problemów.

Treść

Treść wywołania zawiera dane niestandardowe, które mają być wysyłane do usługi Azure Monitor. Kształt danych musi być tablicą JSON ze strukturą elementów zgodną z formatem oczekiwanym przez strumień w kontrolerze domeny. Jeśli konieczne jest wysłanie pojedynczego elementu w ramach wywołania interfejsu API, dane powinny być wysyłane jako tablica z pojedynczym elementem.

Na przykład:

[
{
    "TimeGenerated": "2023-11-14 15:10:02",
    "Column01": "Value01",
    "Column02": "Value02"
}
]

Upewnij się, że treść żądania jest prawidłowo zakodowana w formacie UTF-8, aby zapobiec wszelkim problemom z przesyłaniem danych.

Przykład

Zobacz Przykładowy kod do wysyłania danych do usługi Azure Monitor przy użyciu interfejsu API pozyskiwania dzienników, aby zapoznać się z przykładem wywołania interfejsu API przy użyciu programu PowerShell.

Obsługiwane tabele

Dane wysyłane do interfejsu API pozyskiwania mogą być wysyłane do następujących tabel:

Tabele opis
Tabele niestandardowe Dowolna tabela niestandardowa utworzona w obszarze roboczym usługi Log Analytics. Tabela docelowa musi istnieć przed wysłaniem do niej danych. Tabele niestandardowe muszą mieć _CL sufiks.
Tabele platformy Azure Poniższe tabele platformy Azure są obecnie obsługiwane. Inne tabele można dodać do tej listy, ponieważ jest zaimplementowana obsługa tych tabel.

Uwaga

Nazwy kolumn muszą zaczynać się literą i mogą składać się z maksymalnie 45 znaków alfanumerycznych i podkreśleń (_). _ResourceId, , id_SubscriptionIdTenantIdType_ResourceIdUniqueId, i Title są zastrzeżonymi nazwami kolumn. Kolumny niestandardowe dodawane do tabeli platformy Azure muszą mieć sufiks _CF.

Limity i ograniczenia

Aby uzyskać informacje o limitach związanych z interfejsem API pozyskiwania dzienników, zobacz Limity usługi Azure Monitor.

Następne kroki