Sdílet prostřednictvím

Rozhraní API pro příjem protokolů ve službě Azure Monitor

Rozhraní API pro příjem protokolů ve službě Azure Monitor umožňuje odesílat data do pracovního prostoru služby Log Analytics pomocí volání rozhraní REST API nebo klientských knihoven. Rozhraní API umožňuje odesílat data do podporovaných tabulek Azure nebo do vlastních tabulek, které vytvoříte. Schéma tabulek Azure můžete také rozšířit vlastními sloupci , aby přijímaly další data.

Důležité

Od 1. března 2026 bude rozhraní API pro příjem protokolů vynucovat připojení TLS 1.2 nebo vyšší. Další informace najdete v tématu Zabezpečení dat z logů při přenosu.

Základní operace

Data je možné odesílat do rozhraní API pro příjem protokolů z libovolné aplikace, která může volat REST API. Může se jednat o vlastní aplikaci, kterou vytvoříte, nebo se jedná o aplikaci nebo agenta, která rozumí způsobu odesílání dat do rozhraní API. Určuje pravidlo shromažďování dat (DCR), které zahrnuje cílovou tabulku a pracovní prostor a přihlašovací údaje registrace aplikace s přístupem k zadanému DCR. Odesílá data do koncového bodu určeného řadičem domény nebo do koncového bodu shromažďování dat (DCE), pokud používáte privátní propojení.

Data odesílaná vaší aplikací do rozhraní API musí být naformátovaná ve formátu JSON a musí odpovídat struktuře očekávané dcR. Nemusí nutně odpovídat struktuře cílové tabulky, protože řadič domény může obsahovat transformaci , která převede data tak, aby odpovídala struktuře tabulky. Cílovou tabulku a pracovní prostor můžete upravit úpravou dcR beze změny volání nebo zdrojových dat rozhraní API.

Diagram znázorňující přehled rozhraní API pro příjem dat protokolů

Konfigurace

Následující tabulka popisuje jednotlivé komponenty v Azure, které musíte nakonfigurovat, abyste mohli použít rozhraní API pro příjem protokolů.

Poznámka:

Skript PowerShellu, který automatizuje konfiguraci těchto komponent, najdete v ukázkovém kódu pro odesílání dat do služby Azure Monitor pomocí rozhraní API pro příjem protokolů.

Komponenta Funkce
Registrace a tajný kód aplikace Registrace aplikace se používá k ověření volání rozhraní API. Musí být uděleno povolení pro DCR popsané níže. Volání rozhraní API zahrnuje ID aplikace (klienta) a ID adresáře (tenanta) aplikace a hodnotu tajného kódu aplikace.

Viz Vytvoření aplikace Microsoft Entra a instančního objektu, který má přístup k prostředkům a vytvořit nový tajný klíč aplikace.
Tabulka v pracovním prostoru služby Log Analytics Než do ní budete moct odesílat data, musí existovat tabulka v pracovním prostoru služby Log Analytics. Můžete použít některou z podporovaných tabulek Azure nebo vytvořit vlastní tabulku pomocí některé z dostupných metod. Pokud k vytvoření tabulky použijete Azure Portal, vytvoří se pro vás DCR, včetně transformace, pokud je to potřeba. Pokud máte jinou metodu, musíte dcR vytvořit ručně, jak je popsáno v další části.

Viz Vytvoření vlastní tabulky.
Pravidlo shromažďování dat (DCR) Azure Monitor používá pravidlo shromažďování dat (DCR) k pochopení struktury příchozích dat a toho, co s ním dělat. Pokud se struktura tabulky a příchozích dat neshoduje, řadič domény může obsahovat transformaci , která převede zdrojová data tak, aby odpovídala cílové tabulce. Pomocí transformace můžete také filtrovat zdrojová data a provádět jakékoli jiné výpočty nebo převody.

Pokud vytvoříte vlastní tabulku pomocí portálu Azure, DCR a transformace se pro vás vytvoří na základě vámi poskytnutých ukázkových dat. Pokud používáte existující tabulku nebo vytvoříte vlastní tabulku pomocí jiné metody, musíte DCR vytvořit ručně pomocí podrobností v následující části.

Po vytvoření dcR musíte udělit přístup k aplikaci, kterou jste vytvořili v prvním kroku. V nabídce Monitorování na webu Azure Portal vyberte pravidla shromažďování dat a pak řadič domény, který jste vytvořili. Vyberte Řízení přístupu (IAM) pro DCR a poté vyberte Přidat přiřazení role a přidejte roli Vydavatel metrik monitorování.

Koncový bod

Koncový bod rozhraní REST API pro rozhraní API pro příjem protokolů může být koncový bod shromažďování dat (DCE) nebo koncový bod příjmu protokolů DCR.

Koncový bod příjmu protokolů DCR se vygeneruje při vytváření DCR pro přímý příjem dat. Pokud chcete tento koncový bod načíst, otevřete DCR v zobrazení JSON v Azure portálu. Možná budete muset změnit verzi rozhraní API na nejnovější verzi, aby se koncové body zobrazily.

Snímek obrazovky znázorňující koncový bod příjmu protokolů v DCR

DCE se vyžaduje jenom v případě, že se připojujete k pracovnímu prostoru služby Log Analytics pomocí privátního propojení nebo pokud řadič domény neobsahuje koncový bod pro příjem protokolů. To může být v případě, že používáte starší řadič domény nebo jste vytvořili řadič domény bez parametru "kind": "Direct" . Další podrobnosti najdete níže v tématu Pravidlo shromažďování dat (DCR).

Poznámka:

Vlastnost logsIngestion byla přidána 31. března 2024. Před tímto datem bylo pro rozhraní API určené pro příjem protokolů vyžadováno DCE. Koncové body se nedají přidat do existujícího DCR, ale můžete dál používat jakékoli existující DCR se stávajícími DCE. Pokud chcete přejít na koncový bod DCR, musíte vytvořit nový DCR a nahradit stávající. DCR s koncovými body může také používat DCE. V takovém případě můžete zvolit, jestli se mají používat koncové body DCE nebo DCR pro každého z klientů, kteří používají koncové body DCR.

Pravidlo shromažďování dat (DCR)

Když vytvoříte vlastní tabulku v pracovním prostoru služby Log Analytics pomocí portálu Azure, vytvoří se pro vás DCR, který se dá použít s API pro příjem protokolů. Pokud odesíláte data do tabulky, která už existuje, musíte DCR vytvořit ručně. Začněte ukázkou DCR níže a nahraďte hodnoty následujících parametrů v šabloně. K vytvoření DCR použijte některou z metod popsaných v tématu Vytvoření a úprava pravidel shromažďování dat (DCR) ve službě Azure Monitor .

Parametr Popis
region Oblast pro vytvoření DCR. Pokud ho používáte, musí se shodovat s oblastí pracovního prostoru služby Log Analytics a DCE.
dataCollectionEndpointId ID prostředku vašeho DCE. Pokud používáte DCR bod příjmu, odeberte tento parametr.
streamDeclarations Změňte seznam sloupců na sloupce, které odpovídají vašim příchozím datům. Název streamu nemusíte měnit, stačí, aby odpovídal názvu streams v dataFlows souboru.
workspaceResourceId ID prostředku pracovního prostoru služby Log Analytics Název nemusíte měnit, protože to musí odpovídat názvu destinations v dataFlows.
transformKql Dotaz KQL, který se použije na příchozí data. Pokud schéma příchozích dat odpovídá schématu tabulky, můžete použít source pro transformaci, která příchozí data předá beze změny. V opačném případě použijte dotaz, který transformuje data tak, aby odpovídala schématu cílové tabulky.
outputStream Název tabulky pro odeslání dat Pro vlastní tabulku přidejte předponu Custom-table-name<>. Pro předdefinované tabulky přidejte předponu 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"
            }
        ]
    }
}

Klientské knihovny

Kromě volání rozhraní REST API můžete k odesílání dat do rozhraní API pro příjem protokolů použít následující klientské knihovny. Knihovny vyžadují stejné součásti popsané v konfiguraci. Příklady použití každé z těchto knihoven najdete v ukázkovém kódu pro odesílání dat do služby Azure Monitor pomocí rozhraní API pro příjem protokolů.

Volání rozhraní REST API

Pokud chcete odesílat data do služby Azure Monitor pomocí volání rozhraní REST API, proveďte volání POST přes PROTOKOL HTTPS. Podrobnosti potřebné pro toto volání jsou popsány v této části.

identifikátor URI

Identifikátor URI zahrnuje oblast, koncový bod pro příjem dat DCE nebo DCR, ID DCR a název datového proudu. Určuje také verzi rozhraní API.

Identifikátor URI používá následující formát.

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

Příklad:

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

DCR Immutable ID je generováno pro DCR při jeho vytvoření. Můžete ho načíst ze stránky Přehled dcR na webu Azure Portal.

Snímek obrazovky s pravidlem shromažďování dat zobrazujícím neměnné ID

Stream Name odkazuje na datový proud v DCR, který by měl zpracovávat vlastní data.

Hlavičky žádosti

Následující tabulka popisuje hlavičky požadavků pro volání rozhraní API.

Hlavička Povinný? Popis
Autorizace Ano Nosný token získaný prostřednictvím toku přihlašovacích údajů klienta. Použijte hodnotu cílové skupiny tokenu (rozsah) pro váš cloud:

Veřejný cloud Azure – https://monitor.azure.com
Microsoft Azure provozovaný cloudem 21Vianet – https://monitor.azure.cn
Azure pro vládu USA – https://monitor.azure.us
Typ obsahu Ano application/json
Kódování obsahu Ne gzip
x-ms-client-request-id Ne GUID formátovaný jako řetězec Toto je ID požadavku, které může Microsoft používat pro všechny účely řešení potíží.

Obsah požadavku

Tělo volání obsahuje vlastní data, která se mají odesílat do služby Azure Monitor. Tvar dat musí být pole JSON se strukturou položek, která odpovídá formátu očekávanému datovým proudem v DCR. Tady je příklad pole s jednou položkou.

Příklad:

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

Ujistěte se, že je tělo požadavku správně zakódované v kódování UTF-8, aby se zabránilo problémům s přenosem dat.

Výstraha

Při zanášení protokolů do pomocné úrovně služby Azure Monitor se vyhněte odeslání jedné datové části obsahující časová razítka TimeGenerated, která překračují 30 minut v rámci jednoho volání rozhraní API. Toto volání rozhraní API může vést k následujícímu kódu chyby příjmu dat RecordsTimeRangeIsMoreThan30Minutes. Jedná se o známé omezení, které bude odstraněno.

Toto omezení neplatí pro pomocné protokoly, které používají transformace.

Příklad

Příklad volání rozhraní API pomocí PowerShellu najdete v ukázkovém kódu pro odesílání dat do Azure Monitor pomocí rozhraní API pro příjem protokolů.

Podporované tabulky

Data odesílaná do rozhraní API pro příjem dat je možné odeslat do následujících tabulek:

Tabulky Popis
Vlastní tabulky Libovolná vlastní tabulka, kterou vytvoříte v pracovním prostoru služby Log Analytics. Cílová tabulka musí existovat před odesláním dat. Vlastní tabulky musí mít příponu _CL .
Tabulky Azure V současné době se podporují následující tabulky Azure. Do tohoto seznamu mohou být přidány další tabulky, protože jejich podpora je implementovaná.

Poznámka:

Názvy sloupců musí začínat písmenem a mohou obsahovat až 45 alfanumerických znaků a podtržítka (_). _ResourceId, id, _SubscriptionId, TenantId, , Type, UniqueIda Title jsou vyhrazené názvy sloupců. Vlastní sloupce, které přidáte do tabulky Azure, musí mít příponu _CF.

Limity a omezení

Omezení související s rozhraním API pro příjem protokolů najdete v tématu Omezení služby Azure Monitor.

Další kroky

  • Last updated on