RestApiPoller-Datenkonnektorreferenz für die Codeless Connector Platform

Artikel
09/30/2024

Um einen RestApiPoller Datenconnector mit der Codeless Connector Platform (CCP) zu erstellen, verwenden Sie diese Referenz als Ergänzung zur Microsoft Sentinel-REST-API für Datenconnectors-Dokumente .

Jede dataConnector stellt eine bestimmte Verbindung eines Microsoft Sentinel-Datenconnectors dar. Ein Datenconnector verfügt möglicherweise über mehrere Verbindungen, die Daten aus verschiedenen Endpunkten abrufen. Die JSON-Konfiguration, die mit diesem Referenzdokument erstellt wurde, wird verwendet, um die Bereitstellungsvorlage für den CCP-Datenconnector abzuschließen.

Weitere Informationen finden Sie unter Erstellen eines codelosen Connectors für Microsoft Sentinel.

Datenconnectors – Erstellen oder Aktualisieren

Verweisen Sie auf den Erstellungs- oder Aktualisierungsvorgang in den REST-API-Dokumenten, um die neueste stabile oder Vorschau-API-Version zu finden. Der Unterschied zwischen dem Erstellungs - und dem Aktualisierungsvorgang ist die Aktualisierung, die den etag-Wert erfordert.

PUT-Methode

https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resourceGroupName}}/providers/Microsoft.OperationalInsights/workspaces/{{workspaceName}}/providers/Microsoft.SecurityInsights/dataConnectors/{{dataConnectorId}}?api-version={{apiVersion}}

URI-Parameter

Weitere Informationen zur neuesten API-Version finden Sie unter Data Connectors – Create or Update URI Parameters.

Name	Beschreibung
dataConnectorId	Die Datenconnector-ID muss ein eindeutiger Name sein und ist identisch mit dem `name` Parameter im Anforderungstext.
resourceGroupName	Der Name der Ressourcengruppe, nicht die Groß-/Kleinschreibung.
subscriptionId	Hierbei handelt es sich um die ID des Zielabonnements.
workspaceName	Der Name des Arbeitsbereichs, nicht die ID. RegEx-Muster: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	Hierbei handelt es sich um die für diesen Vorgang zu verwendende API-Version.

Anforderungstext

Der Anforderungstext für einen RestApiPoller CCP-Datenkonnektor hat die folgende Struktur:

{
   "name": "{{dataConnectorId}}",
   "kind": "RestApiPoller",
   "etag": "",
   "properties": {
        "connectorDefinitionName": "",
        "auth": {},
        "request": {},
        "response": {},
        "paging": "",
        "dcrConfig": ""
   }
}

RestApiPoller

RestApiPoller stellt einen API Poller CCP-Datenkonnektor dar, in dem Sie Paging-, Autorisierungs- und Anforderungs-/Antwortnutzlasten für Ihre Datenquelle anpassen.

Name	Erforderlich	Type	BESCHREIBUNG
name	True	Zeichenfolge	Der eindeutige Name der Verbindung, die mit dem URI-Parameter übereinstimmen
kind	True	Zeichenfolge	Muss gleich `RestApiPoller` sein.
etag		GUID	Lassen Sie leer, um neue Connectors zu erstellen. Bei Aktualisierungsvorgängen muss das Etag mit dem Etag (GUID) des vorhandenen Connectors übereinstimmen.
properties.connectorDefinitionName		Zeichenfolge	Der Name der DataConnectorDefinition-Ressource, die die UI-Konfiguration des Datenconnectors definiert. Weitere Informationen finden Sie unter Data Connector Definition.
Eigenschaften.Auth	True	Geschachteltes JSON	Beschreibt die Authentifizierungseigenschaften zum Abfragen der Daten. Weitere Informationen finden Sie unter Authentifizierungskonfiguration.
Eigenschaften.bitten	True	Geschachteltes JSON	Beschreibt die Anforderungsnutzdaten zum Abrufen der Daten, z. B. den API-Endpunkt. Weitere Informationen finden Sie unter Anforderungskonfiguration.
Eigenschaften.Antwort	True	Geschachteltes JSON	Beschreibt das Antwortobjekt und die geschachtelte Nachricht, die beim Abrufen der Daten von der API zurückgegeben werden. Weitere Informationen finden Sie unter Antwortkonfiguration.
Eigenschaften.Seitenüberlagerung		Geschachteltes JSON	Beschreibt die Paginierungsnutzdaten beim Abfragen der Daten. Weitere Informationen finden Sie unter Auslagerungskonfiguration.
Eigenschaften.dcrConfig		Geschachteltes JSON	Erforderliche Parameter, wenn die Daten an eine Datensammlungsregel (Data Collection Rule, DCR) gesendet werden. Weitere Informationen finden Sie unter DCR-Konfiguration.

Authentifizierungskonfiguration

Die CCP unterstützt die folgenden Authentifizierungstypen:

Grundlegend
APIKey
OAuth2
Jwt

Hinweis

Die CCP OAuth2-Implementierung unterstützt keine Clientzertifikatanmeldeinformationen.

Verwenden Sie als bewährte Methode Parameter im Authentifizierungsabschnitt anstelle von hartcodierenden Anmeldeinformationen. Weitere Informationen finden Sie unter Sichere vertrauliche Eingaben.

Um die Bereitstellungsvorlage zu erstellen, die auch Parameter verwendet, müssen Sie die Parameter in diesem Abschnitt mit einem zusätzlichen Start [escapeen. Dadurch können die Parameter einen Wert zuweisen, der auf der Interaktion des Benutzers mit dem Konnektor beruht. Weitere Informationen finden Sie unter Escapezeichen für Vorlagenausdrücke.

Damit die Anmeldeinformationen über die Benutzeroberfläche eingegeben werden können, benötigt instructions der connectorUIConfig Abschnitt die gewünschten Parameter. Weitere Informationen finden Sie in der Datenkonnektordefinitionsreferenz für die Codeless Connector Platform.

Standardauthentifizierung

Feld	Erforderlich	type
UserName	True	Zeichenfolge
Kennwort	True	Zeichenfolge

Beispiel für eine einfache Authentifizierung mithilfe von Parametern, die in connectorUIconfig:

"auth": {
    "type": "Basic",
    "UserName": "[[parameters('username')]",
    "Password": "[[parameters('password')]"
}

APIKey

Feld	Erforderlich	Type	BESCHREIBUNG	Standardwert
ApiKey	True	Zeichenfolge	Geheimer Benutzerschlüssel
ApiKeyName		Zeichenfolge	Name des URI-Headers, der den ApiKey-Wert enthält	`Authorization`
ApiKeyIdentifier		Zeichenfolge	Zeichenfolgenwert, um das Token vorab zu stellen	`token`
IsApiKeyInPostPayload		boolean	Senden eines geheimen Schlüssels im POST-Textkörper anstelle der Kopfzeile	`false`

APIKey-Authentifizierungsbeispiele:

"auth": {
    "type": "APIKey",
    "ApiKey": "[[parameters('apikey')]",
    "ApiKeyName": "X-MyApp-Auth-Header",
    "ApiKeyIdentifier": "Bearer"
}

This example results in the secret defined from user input sent in the following header: X-MyApp-Auth-Header: Bearer apikey

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
}

In diesem Beispiel werden die Standardwerte und Ergebnisse im folgenden Header verwendet: Autorisierung: Token 123123123

"auth": { 
    "type": "APIKey",
    "ApiKey": "123123123",
    "ApiKeyName": ""
}

Da die ApiKeyName Eigenschaft explizit auf "" festgelegt ist, ist das Ergebnis der folgende Kopfzeile: Autorisierung: 123123123

OAuth2

Die Codeless Connector Platform unterstützt die OAuth 2.0-Autorisierungscodezuteilung und Clientanmeldeinformationen. Der Autorisierungscode-Genehmigungstyp wird von vertraulichen und öffentlichen Clients verwendet, um einen Autorisierungscode für ein Zugriffstoken austauschen. Nachdem der Benutzer über die Umleitungs-URL an den Client zurückkehrt, ruft die Anwendung den Autorisierungscode aus der URL ab und verwendet sie, um ein Zugriffstoken anzufordern.

Feld	Erforderlich	Type	Beschreibung
ClientId	True	String	Die Client-ID
ClientSecret	True	String	Den geheimen Clientschlüssel
AuthorizationCode	True, wenn grantType = `authorization_code`	String	Wenn der Grant-Typ dieser Feldwert ist `authorization_code` , ist der Autorisierungscode, der von der Authentifizierungsfunktion zurückgegeben wird.
Umfang	True für `authorization_code` Den Grant-Typ optional für `client_credentials` den Grant-Typ	String	Eine durch Leerzeichen getrennte Liste von Bereichen für die Zustimmung des Benutzers. Weitere Informationen finden Sie unter OAuth2-Bereiche und -Berechtigungen.
Umleitungs-URL	True, wenn grantType = `authorization_code`	String	DIE URL für die Umleitung muss sein. `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	True	String	`authorization_code` oder `client_credentials`
TokenEndpoint	True	String	URL zum Austauschen von Code mit gültigem Token in `authorization_code` "Grant" oder "Client-ID" und "Geheimer Schlüssel" mit gültigem Token in `client_credentials` "Grant".
TokenEndpointHeaders		Objekt	Ein optionales Schlüsselwertobjekt zum Senden von benutzerdefinierten Headern an den Tokenserver
TokenEndpointQueryParameters		Objekt	Ein optionales Schlüsselwertobjekt zum Senden von benutzerdefinierten Abfrageparametern an den Tokenserver
AuthorizationEndpoint	True	String	URL für die Zustimmung des Benutzers für `authorization_code` den Fluss
AuthorizationEndpointHeaders		Objekt	Ein optionales Schlüsselwertobjekt zum Senden von benutzerdefinierten Headern an den Authentifizierungsserver
AuthorizationEndpointQueryParameters		Objekt	Ein optionales Schlüsselwertpaar, das in der OAuth2-Autorisierungscodeflussanforderung verwendet wird

Der Authentifizierungscodefluss dient zum Abrufen von Daten im Auftrag der Berechtigungen eines Benutzers und der Clientanmeldeinformationen zum Abrufen von Daten mit Anwendungsberechtigungen. Der Datenserver gewährt Zugriff auf die Anwendung. Da kein Benutzer im Clientanmeldeinformationsfluss vorhanden ist, ist kein Autorisierungsendpunkt erforderlich, nur ein Tokenendpunkt.

Beispiel: OAuth2-Erteilungstyp authorization_code

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "authorizationEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/authorize",
    "authorizationEndpointHeaders": {},
    "authorizationEndpointQueryParameters": {
        "prompt": "consent"
    },
    "redirectUri": "https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "authorization_code"
}

Beispiel: OAuth2-Erteilungstyp client_credentials

"auth": {
    "type": "OAuth2",
    "ClientId": "[[parameters('appId')]",
    "ClientSecret": "[[parameters('appSecret')]",
    "tokenEndpoint": "https://login.microsoftonline.com/{{tenantId}}/oauth2/v2.0/token",
    "tokenEndpointHeaders": {
        "Accept": "application/json",
        "Content-Type": "application/x-www-form-urlencoded"
    },
    "TokenEndpointQueryParameters": {},
    "scope": "openid offline_access some_scope",
    "grantType": "client_credentials"
}

Jwt

Beispiel: JSON-Webtoken (JWT)

"auth": {
    "type": "JwtToken",
    "userName": {
        "key":"username",
        "value":"[[parameters('UserName')]"
    },
    "password": {
        "key":"password",
        "value":"[[parameters('Password')]"
    },
    "TokenEndpoint": {"https://token_endpoint.contoso.com"},
    "IsJsonRequest": true
}

Anforderungskonfiguration

Der Anforderungsabschnitt definiert, wie der CCP-Datenconnector Anforderungen an Ihre Datenquelle sendet, z. B. den API-Endpunkt und wie oft dieser Endpunkt abgerufen werden soll.

Feld	Erforderlich	Type	BESCHREIBUNG
ApiEndpoint	True	String	URL für Remoteserver. Definiert den Endpunkt, aus dem Daten gepullt werden sollen.
RateLimitQPS		Ganzzahl	Definiert die Anzahl der Aufrufe oder Abfragen, die in einer Sekunde zulässig sind.
QueryWindowInMin		Ganzzahl	Definiert das verfügbare Abfragefenster in Minuten. Der Mindestwert beträgt 1 Minute. Die Standardeinstellung ist 5 Minuten.
HttpMethod		String	Definiert die API-Methode: `GET`(Standard) oder `POST`
QueryTimeFormat		String	Definiert das Datums- und Uhrzeitformat, das der Endpunkt (Remoteserver) erwartet. Die CCP verwendet das aktuelle Datum und die aktuelle Uhrzeit, wo diese Variable verwendet wird. Mögliche Werte sind die Konstanten: `UnixTimestamp`, `UnixTimestampInMills` oder eine andere gültige Darstellung der Datumszeit, z. B.: `yyyy-MM-dd`, `MM/dd/yyyy HH:mm:ss` Standard ist ISO 8601 UTC
RetryCount		Ganze Zahl (1...6)	Definiert die `6` Wiederholungsversuche`1`, die von einem Fehler wiederhergestellt werden dürfen. Der Standardwert ist `3`.
TimeoutInSeconds		Ganze Zahl (1...180)	Definiert das Anforderungstimeout in Sekunden. Der Standardwert ist `20`
IsPostPayloadJson		Boolean	Bestimmt, ob die POST-Nutzdaten im JSON-Format vorliegen. Der Standardwert ist `false`
Headers		Objekt	Schlüsselwertpaare, die die Anforderungsheader definieren.
QueryParameters		Objekt	Schlüsselwertpaare, die die Anforderungsabfrageparameter definieren.
StartTimeAttributeName	True, wenn `EndTimeAttributeName` festgelegt wird	String	Definiert den Abfrageparameternamen für die Startzeit der Abfrage. Siehe Beispiel
EndTimeAttributeName	True, wenn `StartTimeAttributeName` festgelegt wird	String	Definiert den Abfrageparameternamen für die Endzeit der Abfrage.
QueryTimeIntervalAttributeName		String	Wenn für den Endpunkt ein spezielles Format zum Abfragen der Daten in einem Zeitrahmen erforderlich ist, verwenden Sie diese Eigenschaft mit den `QueryTimeIntervalPrepend` Parametern und den `QueryTimeIntervalDelimiter` Parametern. Siehe Beispiel
QueryTimeIntervalPrepend	True, wenn `QueryTimeIntervalAttributeName` festgelegt wird	String	Siehe `QueryTimeIntervalAttributeName`.
QueryTimeIntervalDelimiter	True, wenn `QueryTimeIntervalAttributeName` festgelegt wird	String	Siehe `QueryTimeIntervalAttributeName`.
QueryParametersTemplate		String	Abfragevorlage, die beim Übergeben von Parametern in erweiterten Szenarien verwendet werden soll. br>Beispiel: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

Wenn die API komplexe Parameter erfordert, verwenden Sie die queryParameters oder queryParametersTemplate die einige integrierte Variablen enthalten.

Integrierte Variable	für die Verwendung in `queryParameters`	für die Verwendung in `queryParametersTemplate`
`_QueryWindowStartTime`	ja	Ja
`_QueryWindowEndTime`	Ja	Ja
`_APIKeyName`	Nein	Ja
`_APIKey`	Nein	ja

StartTimeAttributeName-Beispiel

Betrachten Sie das folgende Beispiel:

StartTimeAttributeName = from
EndTimeAttributeName = until
ApiEndpoint = https://www.example.com

Die an den Remoteserver gesendete Abfrage lautet: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

QueryTimeIntervalAttributeName-Beispiel

Betrachten Sie das folgende Beispiel:

QueryTimeIntervalAttributeName = interval
QueryTimeIntervalPrepend = time:
QueryTimeIntervalDelimiter = ..
ApiEndpoint = https://www.example.com

Die an den Remoteserver gesendete Abfrage lautet: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Anfordern von Beispielen mithilfe von Microsoft Graph als Datenquellen-API

In diesem Beispiel werden Nachrichten mit einem Filterabfrageparameter abfragen. Weitere Informationen finden Sie unter Microsoft Graph-API-Abfrageparameter.

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
    "User-Agent": "Example-app-agent"
  },
  "QueryTimeIntervalAttributeName": "filter",
  "QueryTimeIntervalPrepend": "receivedDateTime gt ",
  "QueryTimeIntervalDelimiter": " and receivedDateTime lt "
}

Im vorherigen Beispiel wird eine GET Anforderung an https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Der Zeitstempel wird für jedes queryWindowInMin Mal aktualisiert.

Die gleichen Ergebnisse werden in diesem Beispiel erzielt:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "queryParameters": {
    "filter": "receivedDateTime gt {_QueryWindowStartTime} and receivedDateTime lt {_QueryWindowEndTime}"
  }
}

Eine weitere Option ist, wenn die Datenquelle 2 Abfrageparameter erwartet, eine für die Startzeit und eine für die Endzeit.

Beispiel:

"request": {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/calendarView",
  "httpMethod": "Get",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "StartTimeAttributeName": "startDateTime",
  "EndTimeAttributeName": "endDateTime",
}

Dadurch wird eine GET Anforderung an https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Verwenden Sie QueryParametersTemplatefür komplexe Abfragen . Im nächsten Beispiel wird eine POST Anforderung mit Parametern im Textkörper gesendet.

Beispiel:

request: {
  "apiEndpoint": "https://graph.microsoft.com/v1.0/me/messages",
  "httpMethod": "POST",
  "queryTimeFormat": "yyyy-MM-ddTHH:mm:ssZ",
  "queryWindowInMin": 10,
  "retryCount": 3,
  "rateLimitQPS": 20,
  "headers": {
    "Accept": "application/json",
  },
  "isPostPayloadJson": true,
  "queryParametersTemplate": "{\"query":"TableName | where createdTimestamp between (datetime({_QueryWindowStartTime}) .. datetime({_QueryWindowEndTime}))\"}"
}

Antwortkonfiguration

Definieren Sie die Antwortbehandlung Ihres Datenconnectors mit den folgenden Parametern:

Feld	Erforderlich	Type	BESCHREIBUNG
EventsJsonPaths	True	Liste der Zeichenfolgen	Definiert den Pfad zur Meldung in der JSON-Antwort. Ein JSON-Pfadausdruck gibt einen Pfad zu einem Element oder einer Gruppe von Elementen in einer JSON-Struktur an.
SuccessStatusJsonPath		String	Definiert den Pfad zur Erfolgsmeldung in der JSON-Antwort. Wenn dieser Parameter definiert ist, sollte der `SuccessStatusValue` Parameter ebenfalls definiert werden.
SuccessStatusValue		String	Definiert den Pfad zum Erfolgsmeldungswert in der JSON-Antwort.
IsGzipCompressed		Boolean	Bestimmt, ob die Antwort in einer Gzip-Datei komprimiert wird.
format	True	String	`json` oder `csv` oder `xml`
CompressionAlgo		String	Der Komprimierungsalgorithmus, entweder `multi-gzip` oder `deflate`. Für den Gzip-Komprimierungsalgorithmus konfigurieren Sie `IsGzipCompressed` einfach einen `True` Wert für diesen Parameter.
CsvDelimiter		String	Wenn das Antwortformat CSV ist und Sie das standardmäßige CSV-Trennzeichen von `","`
HasCsvBoundary		Boolean	Angeben, ob CSV-Daten eine Grenze haben
HasCsvHeader		Boolean	Geben Sie an, ob CSV-Daten über eine Kopfzeile verfügen. Der Standardwert ist `True`
CsvEscape		String	Escapezeichen für eine Feldgrenze, Standard ist `"` Beispielsweise erfordert eine CSV-Datei mit Kopfzeilen `id,name,avg` und einer Datenzeile, die Leerzeichen enthält, wie `1,"my name",5.5` die `"` Feldgrenze.
ConvertChildPropertiesToArray		Boolean	Sonderfall, in dem der Remoteserver ein Objekt anstelle einer Liste von Ereignissen zurückgibt, in denen jede Eigenschaft Daten enthält.

Hinweis

Der CSV-Formattyp wird von der RFC4180 Spezifikation analysiert.

Beispiele für die Antwortkonfiguration

Es wird eine Serverantwort im JSON-Format erwartet, wobei die angeforderten Daten im Eigenschaftswert enthalten sind. Der Status der Antworteigenschaft gibt an, dass die Daten nur aufgenommen werden, wenn der Wert istsuccess.

"response": {
  "EventsJsonPaths ": ["$.value"],
  "format": "json",
  "SuccessStatusJsonPath": "$.status",
  "SuccessStatusValue": "success",
  "IsGzipCompressed: true
 }

Die erwartete Antwort in diesem Beispiel bereitet sich auf eine CSV ohne Header vor.

"response": {
  "EventsJsonPaths ": ["$"],
  "format": "csv",
  "HasCsvHeader": false
 }

Auslagerungskonfiguration

Wenn die Datenquelle die gesamte Antwortnutzlast nicht gleichzeitig senden kann, muss der CCP-Datenconnector wissen, wie Teile der Daten auf Antwortseiten empfangen werden. Die paging-Typen, aus denen Sie wählen können, sind:

Seitentyp	Entscheidungsfaktor
LinkHeader PersistentLinkHeader NextPageUrl	Enthält die API-Antwort Links zu nächsten und vorherigen Seiten?
NextPageToken PersistentToken	Verfügt die API-Antwort über ein Token oder Cursor für die nächsten und vorherigen Seiten?
Offset	Unterstützt die API-Antwort einen Parameter für die Anzahl der Objekte, die beim Paging übersprungen werden sollen?

Konfigurieren von LinkHeader oder PersistentLinkHeader

Der am häufigsten verwendete Pagingtyp ist, wenn eine Serverdatenquelle-API URLs für die nächsten und vorherigen Seiten von Daten bereitstellt. Weitere Informationen zur Spezifikation des Linkheaders finden Sie unter RFC 5988.

LinkHeader Paging bedeutet, dass die API-Antwort eine der folgenden Elemente umfasst:

der Link HTTP-Antwortheader
oder einen JSON-Pfad, um den Link aus dem Antworttext abzurufen.

PersistentLinkHeader Paging hat die gleichen Eigenschaften wie LinkHeader, außer der Linkheader bleibt im Back-End-Speicher erhalten. Diese Option ermöglicht das Paging von Verknüpfungen über Abfragefenster hinweg. Beispielsweise unterstützen einige APIs keine Start- oder Endzeiten der Abfrage. Stattdessen unterstützen sie einen serverseitigen Cursor. Beständige Seitentypen können verwendet werden, um den serverseitigen Cursor zu merken. Weitere Informationen finden Sie unter Was ist ein Cursor?.

Hinweis

Es kann nur eine Abfrage für den Connector mit PersistentLinkHeader ausgeführt werden, um Rennbedingungen auf dem serverseitigen Cursor zu vermeiden. Dies kann sich auf die Latenz auswirken.

Feld	Erforderlich	Type	Beschreibung
LinkHeaderTokenJsonPath	False	String	Verwenden Sie diese Eigenschaft, um anzugeben, wo der Wert im Antworttext abgerufen werden soll. Wenn die Datenquelle beispielsweise den folgenden JSON-Code zurückgibt: `{ nextPage: "foo", value: [{data}]}` `LinkHeaderTokenJsonPath$.nextPage`
PageSize	False	Ganzzahl	Anzahl von Ereignissen pro Seite
PageSizeParameterName	False	String	Abfrageparametername für die Seitengröße

Im Folgenden finden Sie einige Beispiele:

Paging: {
  "pagingType": "LinkHeader",
  "linkHeaderTokenJsonPath" : "$.metadata.links.next"
}

Paging: {
 "pagingType" : "PersistentLinkHeader", 
 "pageSizeParameterName" : "limit", 
 "pageSize" : 500 
}

Konfigurieren von NextPageUrl

NextPageUrl Paging bedeutet, dass die API-Antwort einen komplexen Link im Antworttext LinkHeaderähnlich enthält, aber die URL ist im Antworttext anstelle des Headers enthalten.

Feld	Erforderlich	Type	Beschreibung
PageSize	False	Ganzzahl	Anzahl von Ereignissen pro Seite
PageSizeParameterName	False	String	Abfrageparametername für die Seitengröße
NextPageUrl	False	String	Nur, wenn der Connector für Coralogix-API gilt
NextPageUrlQueryParameters	False	Object Key-Wertpaare – Hinzufügen eines benutzerdefinierten Abfrageparameters zu jeder Anforderung für die nächste Seite
NextPageParaName	False	String	Bestimmt den Namen der nächsten Seite in der Anforderung.
HasNextFlagJsonPath	False	String	Definiert den Pfad zum HasNextPage-Flag-Attribut.
NextPageRequestHeader	False	String	Bestimmt den Headernamen der nächsten Seite in der Anforderung.
NextPageUrlQueryParametersTemplate	False	String	Nur, wenn der Connector für Coralogix-API gilt

Beispiel:

Paging: {
 "pagingType" : "NextPageUrl", 
  "nextPageTokenJsonPath" : "$.data.repository.pageInfo.endCursor", 
  "hasNextFlagJsonPath" : "$.data.repository.pageInfo.hasNextPage", 
  "nextPageUrl" : "https://api.github.com/graphql", 
  "nextPageUrlQueryParametersTemplate" : "{'query':'query{repository(owner:\"xyz\")}" 
}

Konfigurieren von NextPageToken oder PersistentToken

NextPageToken Die Paginierung verwendet ein Token (ein Hash oder ein Cursor), der den Status der aktuellen Seite darstellt. Das Token ist in der API-Antwort enthalten, und der Client fügt es an die nächste Anforderung an, um die nächste Seite abzurufen. Diese Methode wird häufig verwendet, wenn der Server den genauen Zustand zwischen Anforderungen beibehalten muss.

PersistentToken Paginierung verwendet ein Token, das serverseitig beibehalten wird. Der Server merkt sich das letzte vom Client abgerufene Token und stellt das nächste Token in nachfolgenden Anforderungen bereit. Der Client wird weiterhin an der Stelle fortgesetzt, an der er aufgehört hat, auch wenn er später neue Anforderungen sendet.

Feld	Erforderlich	Type	Beschreibung
PageSize	False	Ganzzahl	Anzahl von Ereignissen pro Seite
PageSizeParameterName	False	Zeichenfolge	Abfrageparametername für die Seitengröße
NextPageTokenJsonPath	False	Zeichenfolge	JSON-Pfad für das nächste Seitentoken im Antworttext.
NextPageTokenResponseHeader	False	Zeichenfolge	Wenn `NextPageTokenJsonPath` sie leer ist, verwenden Sie das Token in diesem Headernamen für die nächste Seite.
NextPageParaName	False	Zeichenfolge	Bestimmt den Namen der nächsten Seite in der Anforderung.
HasNextFlagJsonPath	False	Zeichenfolge	Definiert den Pfad zu einem HasNextPage-Flag-Attribut , wenn ermittelt wird, ob mehr Seiten in der Antwort verbleiben.
NextPageRequestHeader	False	Zeichenfolge	Bestimmt den Headernamen der nächsten Seite in der Anforderung.

Beispiele:

Paging: {
 "pagingType" : "NextPageToken", 
 "nextPageRequestHeader" : "ETag", 
 "nextPageTokenResponseHeader" : "ETag" 
}

Paging: {
 "pagingType" : "PersistentToken", 
    "nextPageParaName" : "gta", 
    "nextPageTokenJsonPath" : "$.alerts[-1:]._id" 
}

Konfigurieren des Offsets

Offset Die Paginierung gibt die Anzahl der zu überspringenden Seiten und einen Grenzwert für die Anzahl der Ereignisse an, die pro Seite in der Anforderung abgerufen werden sollen. Clients rufen einen bestimmten Bereich von Elementen aus dem Dataset ab.

Feld	Erforderlich	Type	Beschreibung
PageSize	False	Ganzzahl	Anzahl von Ereignissen pro Seite
PageSizeParameterName	False	String	Abfrageparametername für die Seitengröße
OffsetParaName	False	String	Der name des nächsten Anforderungsabfrageparameters. Die CCP berechnet den Offsetwert für jede Anforderung (alle ereignisse, die aufgenommen wurden + 1)

Beispiel:

Paging: {
   
       "pagingType": "Offset", 
        "offsetParaName": "offset" 
 }

DCR-Konfiguration

Feld	Erforderlich	Type	Beschreibung
DataCollectionEndpoint	True	String	DCE (Data Collection Endpoint) for example: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	True	String	Die unveränderliche DCR-ID. Suchen Sie sie, indem Sie die DCR-Erstellungsantwort anzeigen oder die DCR-API verwenden.
StreamName	True	Zeichenfolge	Dieser Wert ist der `streamDeclaration` im DCR definierte Wert (Präfix muss mit "Benutzerdefiniert") beginnen.

Beispiel für CCP-Datenkonnektor

Hier ist ein Beispiel für alle Komponenten des CCP-Datenconnectors JSON zusammen.

{
   "kind": "RestApiPoller",
   "properties": {
      "connectorDefinitionName": "ConnectorDefinitionExample",
      "dcrConfig": {
           "streamName": "Custom-ExampleConnectorInput",
           "dataCollectionEndpoint": "https://example-dce-sbsr.location.ingest.monitor.azure.com",
           "dataCollectionRuleImmutableId": "dcr-32_character_hexadecimal_id"
            },
      "dataType": "ExampleLogs",
      "auth": {
         "type": "Basic",
         "password": "[[parameters('username')]",
         "userName": "[[parameters('password')]"
      },
      "request": {
         "apiEndpoint": "https://rest.contoso.com/example",
         "rateLimitQPS": 10,
         "queryWindowInMin": 5,
         "httpMethod": "GET",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader"
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}

Freigeben über

RestApiPoller-Datenkonnektorreferenz für die Codeless Connector Platform

Datenconnectors – Erstellen oder Aktualisieren

URI-Parameter

Anforderungstext

RestApiPoller

Authentifizierungskonfiguration

Standardauthentifizierung

APIKey

OAuth2

Jwt

Anforderungskonfiguration

StartTimeAttributeName-Beispiel

QueryTimeIntervalAttributeName-Beispiel

Anfordern von Beispielen mithilfe von Microsoft Graph als Datenquellen-API

Antwortkonfiguration

Beispiele für die Antwortkonfiguration

Auslagerungskonfiguration

Konfigurieren von LinkHeader oder PersistentLinkHeader

Konfigurieren von NextPageUrl

Konfigurieren von NextPageToken oder PersistentToken

Konfigurieren des Offsets

DCR-Konfiguration

Beispiel für CCP-Datenkonnektor

Feedback

Zusätzliche Ressourcen