Udostępnij za pośrednictwem

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. 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. Wysyła dane do punktu końcowego określonego przez kontroler domeny lub do punktu końcowego zbierania danych (DCE), jeśli używasz łącza prywatnego.

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).
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.

Punkt końcowy

Punkt końcowy interfejsu API REST dla interfejsu API pozyskiwania dzienników może być punktem końcowym zbierania danych (DCE) lub punktem końcowym pozyskiwania dzienników dcR.

Punkt końcowy pozyskiwania dzienników kontrolera domeny jest generowany podczas tworzenia kontrolera domeny na potrzeby bezpośredniego pozyskiwania. Aby pobrać ten punkt końcowy, otwórz kontroler domeny w widoku JSON w witrynie Azure Portal. Może być konieczne zmianę wersji interfejsu API na najnowszą wersję, aby punkty końcowe mogły być wyświetlane.

Zrzut ekranu przedstawiający punkt końcowy pozyskiwania dzienników w kontrolerze domeny.

Kontroler domeny jest wymagany tylko wtedy, gdy łączysz się z obszarem roboczym usługi Log Analytics przy użyciu łącza prywatnego lub jeśli kontroler domeny nie zawiera punktu końcowego pozyskiwania dzienników. Może się tak zdarzyć, jeśli używasz starszego kontrolera domeny lub jeśli kontroler domeny został utworzony bez parametru "kind": "Direct" . Zobacz Reguła zbierania danych (DCR) poniżej, aby uzyskać więcej informacji.

Uwaga

Obiekt logsIngestion został dodany 31 marca 2024 r. Przed tą datą kontroler domeny był wymagany dla interfejsu API pozyskiwania dzienników. Nie można dodać punktów końcowych do istniejącego kontrolera domeny, ale można nadal używać istniejących kontrolerów domeny z istniejącymi kontrolerami domeny. Jeśli chcesz przejść do punktu końcowego dcR, musisz utworzyć nowy kontroler domeny, aby zastąpić istniejący. Kontroler domeny z punktami końcowymi może również używać kontrolera DOMENY. W takim przypadku można wybrać, czy używać kontrolera domeny, czy punktów końcowych DCR dla każdego z klientów korzystających z kontrolera domeny.

Reguła zbierania danych (DCR)

Podczas tworzenia tabeli niestandardowej w obszarze roboczym usługi Log Analytics przy użyciu witryny Azure Portal tworzony jest kontroler domeny, który może być używany z interfejsem API pozyskiwania dzienników. Jeśli wysyłasz dane do tabeli, która już istnieje, musisz ręcznie utworzyć kontroler domeny. Zacznij od poniższego przykładowego kontrolera domeny, zastępując wartości następujących parametrów w szablonie. 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 obszaru roboczego usługi Log Analytics i dcE, jeśli używasz go.
dataCollectionEndpointId Identyfikator zasobu kontrolera domeny. Usuń ten parametr, jeśli używasz punktu pozyskiwania DCR.
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 do schematu tabeli docelowej.
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><. 
{
    "location": "eastus",
    "dataCollectionEndpointId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/my-resource-group/providers/Microsoft.Insights/dataCollectionEndpoints/dce-eastus",
    "kind": "Direct",
    "properties": {
        "streamDeclarations": {
            "Custom-MyTable": {
                "columns": [
                    {
                        "name": "Time",
                        "type": "datetime"
                    },
                    {
                        "name": "Computer",
                        "type": "string"
                    },
                    {
                        "name": "AdditionalContext",
                        "type": "string"
                    }
                ]
            }
        },
        "destinations": {
            "logAnalytics": [
                {
                    "workspaceResourceId": "/subscriptions/aaaa0a0a-bb1b-cc2c-dd3d-eeeeee4e4e4e/resourceGroups/cefingestion/providers/microsoft.operationalinsights/workspaces/my-workspace",
                    "name": "LogAnalyticsDest"
                }
            ]
        },
        "dataFlows": [
            {
                "streams": [
                    "Custom-MyTable"
                ],
                "destinations": [
                    "LogAnalyticsDest"
                ],
                "transformKql": "source",
                "outputStream": "Custom-MyTable_CL"
            }
        ]
    }
}

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

Identyfikator URI zawiera region, punkt końcowy pozyskiwania dcE lub DCR, identyfikator DCR i nazwę strumienia. Określa również wersję interfejsu API.

Identyfikator URI używa następującego formatu.

{Endpoint}/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

Element DCR Immutable ID jest generowany dla kontrolera domeny podczas jego tworzenia. Możesz pobrać go ze strony Przegląd kontrolera domeny w witrynie Azure Portal.

Zrzut ekranu przedstawiający regułę zbierania danych z niezmiennym identyfikatorem.

Stream Nameodwołuje się do strumienia w kontrolerze domeny, który powinien obsługiwać dane niestandardowe.

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