Informazioni di riferimento sul connettore dati RestApiPoller per la piattaforma del connettore Codeless

Articolo
10/01/2024

Per creare un RestApiPoller connettore dati con la piattaforma CCP (Codeless Connector Platform), usare questo riferimento come supplemento alla documentazione dell'API REST di Microsoft Sentinel per i connettori dati.

Ognuno dataConnector rappresenta una connessione specifica di un connettore dati di Microsoft Sentinel. Un connettore dati potrebbe avere più connessioni, che recuperano i dati da endpoint diversi. La configurazione JSON compilata usando questo documento di riferimento viene usata per completare il modello di distribuzione per il connettore dati CCP.

Per altre informazioni, vedere Creare un connettore senza codice per Microsoft Sentinel.

Connettori dati - Creare o aggiornare

Fare riferimento all'operazione Di creazione o aggiornamento nella documentazione dell'API REST per trovare la versione più recente dell'API stabile o di anteprima. La differenza tra la creazione e l'operazione di aggiornamento è che l'aggiornamento richiede il valore etag .

PUT , metodo

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

Parametri URI

Per altre informazioni sulla versione più recente dell'API, vedere Connettori dati - Creare o aggiornare i parametri URI.

Nome	Descrizione
dataConnectorId	L'ID connettore dati deve essere un nome univoco e corrisponde al `name` parametro nel corpo della richiesta.
resourceGroupName	Nome del gruppo di risorse, senza distinzione tra maiuscole e minuscole.
subscriptionId	ID della sottoscrizione di destinazione.
workspaceName	Nome dell'area di lavoro, non ID. Modello regex: `^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$`
api-version	Versione dell'API da usare per questa operazione.

Testo della richiesta

Il corpo della richiesta per un RestApiPoller connettore dati CCP ha la struttura seguente:

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

RestApiPoller

RestApiPoller rappresenta un connettore dati CCP poller API in cui si personalizzano i payload di paging, autorizzazione e richiesta/risposta per l'origine dati.

Nome	Obbligatorio	Type	Descrizione
name	Vero	string	Nome univoco della connessione corrispondente al parametro URI
kind	Vero	string	Deve essere `RestApiPoller`
etag		GUID	Lasciare vuoto per la creazione di nuovi connettori. Per le operazioni di aggiornamento, l'etag deve corrispondere all'etag (GUID) del connettore esistente.
properties.connectorDefinitionName		string	Nome della risorsa DataConnectorDefinition che definisce la configurazione dell'interfaccia utente del connettore dati. Per altre informazioni, vedere Definizione del connettore dati.
proprietà.Auth	Vero	JSON annidato	Descrive le proprietà di autenticazione per il polling dei dati. Per altre informazioni, vedere Configurazione dell'autenticazione.
proprietà.richiesta	Vero	JSON annidato	Descrive il payload della richiesta per il polling dei dati, ad esempio l'endpoint API. Per altre informazioni, vedere Configurazione della richiesta.
proprietà.risposta	Vero	JSON annidato	Descrive l'oggetto risposta e il messaggio annidato restituito dall'API durante il polling dei dati. Per altre informazioni, vedere Configurazione della risposta.
proprietà.paginazione		JSON annidato	Descrive il payload di paginazione durante il polling dei dati. Per altre informazioni, vedere Configurazione del paging.
proprietà.dcrConfig		JSON annidato	Parametri obbligatori quando i dati vengono inviati a una regola di raccolta dati. Per altre informazioni, vedere Configurazione DCR.

Configurazione dell'autenticazione

Il CCP supporta i tipi di autenticazione seguenti:

Base
APIKey
OAuth2
Jwt

Nota

L'implementazione OAuth2 di CCP non supporta le credenziali del certificato client.

Come procedura consigliata, usare i parametri nella sezione di autenticazione anziché le credenziali hardcoded. Per altre informazioni, vedere Proteggere l'input riservato.

Per creare il modello di distribuzione che usa anche i parametri, è necessario eseguire l'escape dei parametri in questa sezione con un'avvio aggiuntivo [. In questo modo i parametri possono assegnare un valore in base all'interazione dell'utente con il connettore. Per altre informazioni, vedere Caratteri di escape delle espressioni modello.

Per abilitare l'immissione delle credenziali dall'interfaccia utente, la connectorUIConfig sezione richiede instructions i parametri desiderati. Per altre informazioni, vedere Informazioni di riferimento sulle definizioni dei connettori dati per la piattaforma del connettore Codeless.

Autenticazione di base

Campo	Richiesto	Type
UserName	Vero	string
Password	Vero	string

Esempio di autenticazione di base usando i parametri definiti in connectorUIconfig:

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

APIKey

Campo	Richiesto	Type	Descrizione	Default value
ApiKey	Vero	string	chiave privata utente
ApiKeyName		string	nome dell'intestazione URI contenente il valore ApiKey	`Authorization`
ApiKeyIdentifier		string	valore stringa per anteporre il token	`token`
IsApiKeyInPostPayload		boolean	inviare il segreto nel corpo POST anziché nell'intestazione	`false`

Esempi di autenticazione APIKey:

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

Questo esempio restituisce il segreto definito dall'input dell'utente inviato nell'intestazione seguente: X-MyApp-Auth-Header: Bearer apikey

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

Questo esempio usa i valori predefiniti e restituisce l'intestazione seguente: Autorizzazione: token 123123123

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

Poiché è ApiKeyName impostato in modo esplicito su "", il risultato è l'intestazione seguente: Autorizzazione: 123123123

OAuth2

La piattaforma del connettore Codeless supporta la concessione del codice di autorizzazione OAuth 2.0 e le credenziali client. Il tipo di concessione del codice di autorizzazione viene usato dai client riservati e pubblici per scambiare un codice di autorizzazione per un token di accesso. Dopo che l'utente torna al client tramite l'URL di reindirizzamento, l'applicazione otterrà il codice di autorizzazione dall'URL e lo userà per richiedere un token di accesso.

Campo	Richiesto	Type	Descrizione
ClientId	Vero	String	ID client
ClientSecret	Vero	String	Segreto client
AuthorizationCode	True quando grantType = `authorization_code`	String	Se il tipo di concessione è `authorization_code` questo valore di campo, sarà il codice di autorizzazione restituito dal servizio di autenticazione.
Scope	True per `authorization_code` il tipo di concessione facoltativo per `client_credentials` il tipo di concessione	String	Elenco di ambiti separati da spazi per il consenso dell'utente. Per altre informazioni, vedere Ambiti e autorizzazioni OAuth2.
RedirectUri	True quando grantType = `authorization_code`	String	L'URL per il reindirizzamento deve essere `https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights`
GrantType	Vero	String	`authorization_code` oppure `client_credentials`
TokenEndpoint	Vero	String	URL per lo scambio di codice con token valido in `authorization_code` concessione o ID client e segreto con token valido nella `client_credentials` concessione.
TokenEndpointHeaders		Object	Oggetto valore chiave facoltativo per inviare intestazioni personalizzate al server token
TokenEndpointQueryParameters		Object	Oggetto valore chiave facoltativo per inviare parametri di query personalizzati al server token
AuthorizationEndpoint	Vero	String	URL per il consenso dell'utente per `authorization_code` il flusso
AuthorizationEndpointHeaders		Object	Oggetto valore chiave facoltativo per inviare intestazioni personalizzate al server di autenticazione
AuthorizationEndpointQueryParameters		Object	Coppia di valori di chiave facoltativa usata nella richiesta del flusso del codice di autorizzazione OAuth2

Il flusso di codice di autenticazione è destinato al recupero dei dati per conto delle autorizzazioni di un utente e delle credenziali client per il recupero dei dati con autorizzazioni dell'applicazione. Il server dati concede l'accesso all'applicazione. Poiché non è presente alcun utente nel flusso delle credenziali client, non è necessario alcun endpoint di autorizzazione, ma solo un endpoint del token.

Esempio: tipo di concessione OAuth2 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"
}

Esempio: tipo di concessione OAuth2 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

Esempio: token Web JSON (JWT)

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

Richiedere la configurazione

La sezione della richiesta definisce il modo in cui il connettore dati CCP invia richieste all'origine dati, ad esempio l'endpoint API e la frequenza con cui eseguire il polling dell'endpoint.

Campo	Richiesto	Type	Descrizione
ApiEndpoint	Vero	String	URL per il server remoto. Definisce l'endpoint da cui eseguire il pull dei dati.
RateLimitQPS		Intero	Definisce il numero di chiamate o query consentite in un secondo.
QueryWindowInMin		Intero	Definisce la finestra di query disponibile in minuti. Il valore minimo è 1 minuto. Il valore predefinito è 5 minuti.
HttpMethod		String	Definisce il metodo API: `GET`(impostazione predefinita) o `POST`
QueryTimeFormat		String	Definisce il formato di data e ora previsto dall'endpoint (server remoto). Il CCP usa la data e l'ora correnti ovunque venga usata questa variabile. I valori possibili sono le costanti: `UnixTimestampUnixTimestampInMills` o qualsiasi altra rappresentazione valida di data e ora, ad esempio: `yyyy-MM-dd`,`MM/dd/yyyy HH:mm:ss` il valore predefinito è ISO 8601 UTC
RetryCount		Intero (1...6)	Definisce `1` per ritentare `6` il ripristino da un errore. Il valore predefinito è `3`.
TimeoutInSeconds		Intero (1...180)	Definisce il timeout della richiesta, espresso in secondi. L'impostazione predefinita è `20`
IsPostPayloadJson		Booleano	Determina se il payload POST è in formato JSON. L'impostazione predefinita è `false`
Intestazioni		Object	Coppie chiave-valore che definiscono le intestazioni della richiesta.
QueryParameters		Object	Coppie chiave-valore che definiscono i parametri di query della richiesta.
StartTimeAttributeName	True quando `EndTimeAttributeName` è impostato	String	Definisce il nome del parametro di query per l'ora di inizio della query. Vedere l'esempio.
EndTimeAttributeName	True quando `StartTimeAttributeName` è impostato	String	Definisce il nome del parametro di query per l'ora di fine della query.
QueryTimeIntervalAttributeName		String	Se l'endpoint richiede un formato specializzato per eseguire query sui dati in un intervallo di tempo, usare questa proprietà con i `QueryTimeIntervalPrepend` parametri e `QueryTimeIntervalDelimiter` . Vedere l'esempio.
QueryTimeIntervalPrepend	True quando `QueryTimeIntervalAttributeName` è impostato	String	Vedere `QueryTimeIntervalAttributeName`
QueryTimeIntervalDelimiter	True quando `QueryTimeIntervalAttributeName` è impostato	String	Vedere `QueryTimeIntervalAttributeName`
QueryParametersTemplate		String	Modello di query da usare per il passaggio di parametri in scenari avanzati. br>Ad esempio: `"queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}"`

Quando l'API richiede parametri complessi, usare queryParameters o queryParametersTemplate che includono alcune variabili predefinite.

Variabile predefinita	per l'uso in `queryParameters`	per l'uso in `queryParametersTemplate`
`_QueryWindowStartTime`	yes	sì
`_QueryWindowEndTime`	sì	sì
`_APIKeyName`	no	yes
`_APIKey`	no	yes

Esempio di StartTimeAttributeName

Si consideri questo esempio:

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

La query inviata al server remoto è: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}

Esempio di QueryTimeIntervalAttributeName

Si consideri questo esempio:

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

La query inviata al server remoto è: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}

Richiedere esempi usando Microsoft Graph come API origine dati

In questo esempio vengono eseguite query sui messaggi con un parametro di query di filtro. Per altre informazioni, vedere Parametri di query dell'API Microsoft Graph.

"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 "
}

Nell'esempio precedente viene inviata una GET richiesta a https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. Il timestamp viene aggiornato per ogni queryWindowInMin volta.

Gli stessi risultati vengono ottenuti con questo esempio:

"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}"
  }
}

Un'altra opzione è quando l'origine dati prevede 2 parametri di query, uno per l'ora di inizio e uno per l'ora di fine.

Esempio:

"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",
}

In questo modo viene inviata una GET richiesta a https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000

Per le query complesse, usare QueryParametersTemplate. Nell'esempio seguente viene inviata una POST richiesta con parametri nel corpo.

Esempio:

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}))\"}"
}

Configurazione della risposta

Definire la gestione delle risposte del connettore dati con i parametri seguenti:

Campo	Richiesto	Type	Descrizione
EventsJsonPaths	Vero	Elenco di stringhe	Definisce il percorso del messaggio nel codice JSON della risposta. Un'espressione di percorso JSON specifica un percorso di un elemento o un set di elementi in una struttura JSON
SuccessStatusJsonPath		String	Definisce il percorso del messaggio di operazione riuscita nel codice JSON della risposta. Quando questo parametro è definito, è necessario definire anche il `SuccessStatusValue` parametro .
SuccessStatusValue		String	Definisce il percorso del valore del messaggio di operazione riuscita nel codice JSON della risposta
IsGzipCompressed		Booleano	Determina se la risposta è compressa in un file gzip
format	Vero	String	`json` o `csv` o `xml`
CompressionAlgo		String	Algoritmo di compressione, `multi-gzip` o `deflate`. Per l'algoritmo di compressione gzip, è sufficiente configurare `IsGzipCompressed` `True` invece di impostare un valore per questo parametro.
CsvDelimiter		String	Se il formato della risposta è CSV e si vuole modificare il delimitatore CSV predefinito di `","`
HasCsvBoundary		Booleano	Indicare se i dati CSV hanno un limite
HasCsvHeader		Booleano	Indicare se i dati CSV hanno un'intestazione, il valore predefinito è `True`
CsvEscape		String	Carattere di escape per un limite di campo. Il valore predefinito è `"` Ad esempio, un file CSV con intestazioni `id,name,avg` e una riga di dati contenenti spazi come `1,"my name",5.5` richiede il limite del `"` campo.
ConvertChildPropertiesToArray		Booleano	Caso speciale in cui il server remoto restituisce un oggetto anziché un elenco di eventi in cui ogni proprietà contiene dati.

Nota

Il tipo di formato CSV viene analizzato in base alla specifica RFC4180 .

Esempi di configurazione della risposta

È prevista una risposta del server con formato JSON, con i dati richiesti nel valore della proprietà. Lo stato della proprietà di risposta indica di inserire i dati solo se il valore è success.

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

La risposta prevista in questo esempio viene preparata per un file CSV senza intestazione.

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

Configurazione del paging

Quando l'origine dati non può inviare l'intero payload della risposta contemporaneamente, il connettore dati CCP deve sapere come ricevere parti dei dati nelle pagine di risposta. I tipi di paging tra cui scegliere sono:

Tipo di paging	fattore decisionale
LinkHeader PersistentLinkHeader NextPageUrl	La risposta dell'API include collegamenti alle pagine successive e precedenti?
NextPageToken PersistentToken	La risposta api ha un token o un cursore per le pagine successive e precedenti?
Offset	La risposta API supporta un parametro per il numero di oggetti da ignorare durante il paging?

Configurare LinkHeader o PersistentLinkHeader

Il tipo di paging più comune è quando un'API dell'origine dati del server fornisce GLI URL alle pagine successive e precedenti di dati. Per altre informazioni sulla specifica intestazione del collegamento, vedere RFC 5988.

LinkHeader il paging indica che la risposta dell'API include:

intestazione della Link risposta HTTP
o un percorso JSON per recuperare il collegamento dal corpo della risposta.

PersistentLinkHeader il paging ha le stesse proprietà di LinkHeader, ad eccezione dell'intestazione del collegamento persistente nell'archiviazione back-end. Questa opzione abilita i collegamenti di paging nelle finestre di query. Alcune API, ad esempio, non supportano le ore di inizio o di fine delle query. Supportano invece un cursore lato server. I tipi di pagina persistenti possono essere usati per ricordare il cursore sul lato server. Per altre informazioni, vedere Che cos'è un cursore?.

Nota

È possibile eseguire una sola query per il connettore con PersistentLinkHeader per evitare race condition sul cursore sul lato server. Ciò può influire sulla latenza.

Campo	Richiesto	Type	Descrizione
LinkHeaderTokenJsonPath	Falso	String	Utilizzare questa proprietà per indicare dove ottenere il valore nel corpo della risposta. Ad esempio, se l'origine dati restituisce il codice JSON seguente: `{ nextPage: "foo", value: [{data}]}` `LinkHeaderTokenJsonPath$.nextPage`
PageSize	Falso	Intero	Numero di eventi per pagina
PageSizeParameterName	Falso	String	Nome del parametro di query per le dimensioni della pagina

Di seguito sono riportati alcuni esempi.

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

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

Configurare NextPageUrl

NextPageUrl il paging indica che la risposta dell'API include un collegamento complesso nel corpo della risposta simile a LinkHeader, ma l'URL è incluso nel corpo della risposta anziché nell'intestazione.

Campo	Richiesto	Type	Descrizione
PageSize	Falso	Intero	Numero di eventi per pagina
PageSizeParameterName	Falso	String	Nome del parametro di query per le dimensioni della pagina
NextPageUrl	Falso	String	Solo se il connettore è per l'API Coralogix
NextPageUrlQueryParameters	Falso	Coppie chiave oggetto - Aggiunta di un parametro di query personalizzato a ogni richiesta per la pagina successiva
NextPageParaName	Falso	String	Determina il nome della pagina successiva nella richiesta.
HasNextFlagJsonPath	Falso	String	Definisce il percorso dell'attributo flag HasNextPage
NextPageRequestHeader	Falso	String	Determina il nome dell'intestazione della pagina successiva nella richiesta.
NextPageUrlQueryParametersTemplate	Falso	String	Solo se il connettore è per l'API Coralogix

Esempio:

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\")}" 
}

Configurare NextPageToken o PersistentToken

NextPageToken la paginazione usa un token (un hash o un cursore) che rappresenta lo stato della pagina corrente. Il token è incluso nella risposta dell'API e il client lo aggiunge alla richiesta successiva per recuperare la pagina successiva. Questo metodo viene spesso usato quando il server deve mantenere lo stato esatto tra le richieste.

PersistentToken la paginazione usa un token che rende persistente il lato server. Il server memorizza l'ultimo token recuperato dal client e fornisce il token successivo nelle richieste successive. Il client continua dove è stato interrotto anche se effettua nuove richieste in un secondo momento.

Campo	Richiesto	Type	Descrizione
PageSize	Falso	Intero	Numero di eventi per pagina
PageSizeParameterName	Falso	string	Nome del parametro di query per le dimensioni della pagina
NextPageTokenJsonPath	Falso	string	Percorso JSON per il token di pagina successivo nel corpo della risposta.
NextPageTokenResponseHeader	Falso	string	Se `NextPageTokenJsonPath` è vuoto, usare il token nel nome dell'intestazione per la pagina successiva.
NextPageParaName	Falso	string	Determina il nome della pagina successiva nella richiesta.
HasNextFlagJsonPath	Falso	string	Definisce il percorso di un attributo del flag HasNextPage quando si determina se nella risposta vengono lasciate altre pagine.
NextPageRequestHeader	Falso	string	Determina il nome dell'intestazione della pagina successiva nella richiesta.

Esempi:

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

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

Configurare l'offset

Offset paginazione specifica il numero di pagine da ignorare e un limite al numero di eventi da recuperare per pagina nella richiesta. I client recuperano un intervallo specifico di elementi dal set di dati.

Campo	Richiesto	Type	Descrizione
PageSize	Falso	Intero	Numero di eventi per pagina
PageSizeParameterName	Falso	String	Nome del parametro di query per le dimensioni della pagina
OffsetParaName	Falso	String	Nome del parametro di query della richiesta successiva. Il CCP calcola il valore di offset per ogni richiesta, (tutti gli eventi inseriti + 1)

Esempio:

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

Configurazione di DCR

Campo	Richiesto	Type	Descrizione
DataCollectionEndpoint	Vero	String	DCE (endpoint di raccolta dati), ad esempio: `https://example.ingest.monitor.azure.com`.
DataCollectionRuleImmutableId	Vero	String	ID non modificabile DCR. Trovarlo visualizzando la risposta di creazione del DCR o usando l'API DCR
StreamName	Vero	string	Questo valore è il definito nel registro di controllo di `streamDeclaration` dominio (il prefisso deve iniziare con Custom-)

Connettore dati CCP di esempio

Ecco un esempio di tutti i componenti del connettore dati CCP insieme.

{
   "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": ["$"]
      }
   }
}

Condividi tramite

Informazioni di riferimento sul connettore dati RestApiPoller per la piattaforma del connettore Codeless

Connettori dati - Creare o aggiornare

Parametri URI

Testo della richiesta

RestApiPoller

Configurazione dell'autenticazione

Autenticazione di base

APIKey

OAuth2

Jwt

Richiedere la configurazione

Esempio di StartTimeAttributeName

Esempio di QueryTimeIntervalAttributeName

Richiedere esempi usando Microsoft Graph come API origine dati

Configurazione della risposta

Esempi di configurazione della risposta

Configurazione del paging

Configurare LinkHeader o PersistentLinkHeader

Configurare NextPageUrl

Configurare NextPageToken o PersistentToken

Configurare l'offset

Configurazione di DCR

Connettore dati CCP di esempio

Commenti e suggerimenti

Risorse aggiuntive