Logboekopname-API in Azure Monitor

  • Artikel

Met de Logboekopname-API in Azure Monitor kunt u gegevens verzenden naar een Log Analytics-werkruimte met behulp van een REST API-aanroep of clientbibliotheken. Met de API kunt u gegevens verzenden naar ondersteunde Azure-tabellen of naar aangepaste tabellen die u maakt. U kunt ook het schema van Azure-tabellen uitbreiden met aangepaste kolommen om aanvullende gegevens te accepteren.

Basisbewerking

Gegevens kunnen worden verzonden naar de Logboekopname-API vanuit elke toepassing die een REST API-aanroep kan maken. Dit kan een aangepaste toepassing zijn die u maakt, of het kan een toepassing of agent zijn die begrijpt hoe u gegevens naar de API verzendt. De toepassing verzendt gegevens naar een eindpunt voor gegevensverzameling (DCE), een uniek verbindingspunt voor uw Azure-abonnement. Hiermee geeft u een regel voor gegevensverzameling (DCR) op die de doeltabel en werkruimte en de referenties van een app-registratie met toegang tot de opgegeven DCR bevat.

De gegevens die door uw toepassing naar de API worden verzonden, moeten worden opgemaakt in JSON en overeenkomen met de structuur die door de DCR wordt verwacht. Het hoeft niet per se overeen te komen met de structuur van de doeltabel, omdat de DCR een transformatie kan bevatten om de gegevens te converteren zodat deze overeenkomen met de structuur van de tabel. U kunt de doeltabel en werkruimte wijzigen door de DCR te wijzigen zonder de API-aanroep of brongegevens te wijzigen.

Diagram met een overzicht van de API voor logboekopname.

Configuratie

In de volgende tabel wordt elk onderdeel in Azure beschreven dat u moet configureren voordat u de API voor logboekopname kunt gebruiken.

Notitie

Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor een PowerShell-script waarmee de configuratie van deze onderdelen wordt geautomatiseerd.

Onderdeel Functie
App-registratie en -geheim De toepassingsregistratie wordt gebruikt om de API-aanroep te verifiëren. Het moet toestemming worden verleend aan de DCR die hieronder wordt beschreven. De API-aanroep bevat de id van de toepassing (client) en de map-id (tenant) van de toepassing en de waarde van een toepassingsgeheim.

Zie Een Microsoft Entra-toepassing en service-principal maken die toegang heeft tot resources en een nieuw toepassingsgeheim maken.
Eindpunt voor gegevensverzameling (DCE) De DCE biedt een eindpunt waar de toepassing naartoe kan verzenden. Eén DCE kan meerdere DCR's ondersteunen, zodat u een bestaande DCE kunt gebruiken als u er al een hebt in dezelfde regio als uw Log Analytics-werkruimte.

Zie Een eindpunt voor gegevensverzameling maken.
Tabel in Log Analytics-werkruimte De tabel in de Log Analytics-werkruimte moet bestaan voordat u er gegevens naar kunt verzenden. U kunt een van de ondersteunde Azure-tabellen gebruiken of een aangepaste tabel maken met behulp van een van de beschikbare methoden. Als u Azure Portal gebruikt om de tabel te maken, wordt de DCR voor u gemaakt, inclusief een transformatie als deze vereist is. Met een andere methode moet u de DCR handmatig maken zoals beschreven in de volgende sectie.

Zie Een aangepaste tabel maken.
Regel voor gegevensverzameling (DCR) Azure Monitor maakt gebruik van de regel voor gegevensverzameling (DCR) om inzicht te hebben in de structuur van de binnenkomende gegevens en wat u ermee moet doen. Als de structuur van de tabel en de binnenkomende gegevens niet overeenkomen, kan de DCR een transformatie bevatten om de brongegevens te converteren zodat deze overeenkomen met de doeltabel. U kunt de transformatie ook gebruiken om brongegevens te filteren en andere berekeningen of conversies uit te voeren.

Als u een aangepaste tabel maakt met behulp van Azure Portal, worden de DCR en de transformatie voor u gemaakt op basis van voorbeeldgegevens die u opgeeft. Als u een bestaande tabel gebruikt of een aangepaste tabel maakt met een andere methode, moet u de DCR handmatig maken met behulp van details in de volgende sectie.

Zodra uw DCR is gemaakt, moet u er toegang toe verlenen voor de toepassing die u in de eerste stap hebt gemaakt. Selecteer in het menu Monitor in Azure Portal regels voor gegevensverzameling en vervolgens de DCR die u hebt gemaakt. Selecteer Toegangsbeheer (IAM) voor de DCR en selecteer vervolgens Roltoewijzing toevoegen om de rol Monitoring Metrics Publisher toe te voegen.

DCR handmatig maken

Als u gegevens verzendt naar een tabel die al bestaat, moet u de DCR handmatig maken. Begin met de VOORBEELD-DCR voor logboekopname-API en wijzig de volgende parameters in de sjabloon. Gebruik vervolgens een van de methoden die worden beschreven in DCR's (Data Collection Rules) maken en bewerken in Azure Monitor om de DCR te maken.

Parameter Description
region Regio om uw DCR te maken. Dit moet overeenkomen met de regio van de DCE en de Log Analytics-werkruimte.
dataCollectionEndpointId Resource-id van uw DCE.
streamDeclarations Wijzig de kolomlijst in de kolommen in uw binnenkomende gegevens. U hoeft de naam van de stream niet te wijzigen, omdat dit alleen moet overeenkomen met de streams naam in dataFlows.
workspaceResourceId Resource-id van uw Log Analytics-werkruimte. U hoeft de naam niet te wijzigen, omdat deze alleen moet overeenkomen met de destinations naam in dataFlows.
transformKql KQL-query die moet worden toegepast op de binnenkomende gegevens. Als het schema van de binnenkomende gegevens overeenkomt met het schema van de tabel, kunt u gebruiken source voor de transformatie die de binnenkomende gegevens ongewijzigd doorgeeft. Gebruik anders een query waarmee de gegevens worden getransformeerd zodat deze overeenkomen met het tabelschema.
outputStream De naam van de tabel om de gegevens te verzenden. Voeg voor een aangepaste tabel het voorvoegsel Custom-table-name<> toe. Voeg voor een ingebouwde tabel het voorvoegsel Microsoft-tabelnaam<> toe.

Clientbibliotheken

Naast het maken van een REST API-aanroep kunt u de volgende clientbibliotheken gebruiken om gegevens te verzenden naar de logboekopname-API. Voor de bibliotheken zijn dezelfde onderdelen vereist die worden beschreven in Configuratie. Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor voorbeelden van elk van deze bibliotheken.

REST API-aanroep

Als u gegevens wilt verzenden naar Azure Monitor met een REST API-aanroep, voert u een POST-aanroep via HTTP uit. Details die vereist zijn voor deze aanroep, worden beschreven in deze sectie.

Eindpunt-URI

De eindpunt-URI gebruikt de volgende indeling, waarbij de Data Collection EndpointDCR Immutable ID DCE en DCR worden geïdentificeerd. De onveranderbare id wordt gegenereerd voor de DCR wanneer deze wordt gemaakt. U kunt deze ophalen uit de JSON-weergave van de DCR in Azure Portal. Stream Name verwijst naar de stroom in de DCR die de aangepaste gegevens moet verwerken.

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

Voorbeeld:

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

Kopteksten

In de volgende tabel worden die headers voor uw API-aanroep beschreven.

Koptekst Vereist? Beschrijving
Autorisatie Ja Bearer-token dat is verkregen via de clientreferentiestroom. Gebruik de tokendoelwaarde voor uw cloud:

Openbare Azure-cloud - https://monitor.azure.com
Microsoft Azure beheerd door 21Vianet-cloud - https://monitor.azure.cn
Azure US Government-cloud - https://monitor.azure.us
Inhoudstype Ja application/json
Content-Encoding Nee gzip
x-ms-client-request-id Nee Guid met tekenreeksindeling. Dit is een aanvraag-id die door Microsoft kan worden gebruikt voor probleemoplossingsdoeleinden.

Hoofdtekst

De hoofdtekst van de aanroep bevat de aangepaste gegevens die naar Azure Monitor moeten worden verzonden. De vorm van de gegevens moet een JSON-matrix met itemstructuur zijn die overeenkomt met de indeling die door de stream in de DCR wordt verwacht. Als het nodig is om één item binnen de API-aanroep te verzenden, moeten de gegevens worden verzonden als een matrix met één item.

Voorbeeld:

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

Zorg ervoor dat de aanvraagbody correct is gecodeerd in UTF-8 om problemen met gegevensoverdracht te voorkomen.

Opmerking

Zie Voorbeeldcode voor het verzenden van gegevens naar Azure Monitor met behulp van logboekopname-API voor een voorbeeld van de API-aanroep met behulp van PowerShell.

Ondersteunde tabellen

Gegevens die naar de opname-API worden verzonden, kunnen worden verzonden naar de volgende tabellen:

Tabellen Beschrijving
Aangepaste tabellen Elke aangepaste tabel die u in uw Log Analytics-werkruimte maakt. De doeltabel moet bestaan voordat u er gegevens naar kunt verzenden. Aangepaste tabellen moeten het _CL achtervoegsel hebben.
Azure-tabellen De volgende Azure-tabellen worden momenteel ondersteund. Andere tabellen kunnen aan deze lijst worden toegevoegd als ondersteuning voor deze tabellen wordt geïmplementeerd.

Notitie

Kolomnamen moeten beginnen met een letter en kunnen bestaan uit maximaal 45 alfanumerieke tekens en onderstrepingstekens (_). _ResourceId, , _ResourceIdid, _SubscriptionId, , TenantId, , Typeen TitleUniqueIdzijn gereserveerde kolomnamen. Aangepaste kolommen die u aan een Azure-tabel toevoegt, moeten het achtervoegsel _CFhebben.

Limieten en beperkingen

Zie Azure Monitor-servicelimieten voor limieten met betrekking tot de Logboekopname-API.

Volgende stappen