Informazioni di riferimento sul connettore dati RestApiPoller per codeless Connector Framework

È possibile creare un RestApiPoller connettore dati con Codeless Connector Framework (CCF) usando questo articolo come supplemento alla documentazione relativa all'API REST Microsoft Sentinel per i connettori dati.

Ogni connettore dati rappresenta una connessione specifica di un connettore dati Microsoft Sentinel. Un connettore dati potrebbe avere più connessioni, che recuperano dati da endpoint diversi. È possibile completare il modello di distribuzione per il connettore dati CCF usando la configurazione JSON compilata con questo articolo.

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

Creazione o aggiornamento di connettori dati

Trovare la versione più recente dell'API stabile o di anteprima facendo riferimento alle create operazioni o update nella documentazione dell'API REST. La differenza tra le create operazioni e update è che update richiede il etag valore .

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 di dati: creare o aggiornare i parametri URI.

Nome Descrizione
dataConnectorId ID connettore dati. Deve essere un nome univoco uguale 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.
Il modello regex è ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$.
api-version Versione dell'API da usare per questa operazione.

Corpo della richiesta

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

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

RestApiPoller

RestApiPoller è un connettore dati CCF del poller API che è possibile usare per personalizzare i payload di paging, autorizzazione e richiesta/risposta per l'origine dati.

Nome Obbligatorio Tipo Descrizione
name Vero Stringa Nome univoco della connessione che corrisponde al parametro URI.
kind Vero Stringa Valore kind . Questo campo deve essere impostato su RestApiPoller.
etag GUID Valore etag . Questo campo deve essere lasciato vuoto per la creazione del nuovo connettore. Per le operazioni di aggiornamento, etag deve corrispondere al connettore etag esistente (GUID).
properties.connectorDefinitionName Stringa Nome della DataConnectorDefinition risorsa che definisce la configurazione dell'interfaccia utente del connettore dati. Per altre informazioni, vedere Definizione del connettore dati.
properties.auth Vero JSON annidato Proprietà di autenticazione per il polling dei dati. Per altre informazioni, vedere Configurazione dell'autenticazione.
properties.request Vero JSON annidato Payload della richiesta per il polling dei dati, ad esempio l'endpoint API. Per altre informazioni, vedere Configurazione della richiesta.
properties. response Vero JSON annidato L'oggetto risposta e il messaggio annidato restituiti dall'API quando esegue il polling dei dati. Per altre informazioni, vedere Configurazione della risposta.
properties.paging JSON annidato Payload di impaginazione durante il polling dei dati. Per altre informazioni, vedere Configurazione del paging.
properties.dcrConfig JSON annidato Parametri obbligatori quando i dati vengono inviati a una regola di raccolta dati (DCR). Per altre informazioni, vedere Configurazione DCR.

Configurazione dell'autenticazione

Il CCF supporta i tipi di autenticazione seguenti:

Nota

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

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

Per creare il modello di distribuzione, che usa anche parametri, è necessario eseguire l'escape dei parametri in questa sezione con un elemento di avvio [aggiuntivo. Questo passaggio consente ai parametri di 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, nella connectorUIConfig sezione è necessario immettere i parametri desiderati in instructions. Per altre informazioni, vedere Informazioni di riferimento sulle definizioni del connettore dati per Codeless Connector Framework.

Autenticazione di base

Campo Obbligatorio Tipo
UserName Vero Stringa
Password Vero Stringa

Ecco un esempio di autenticazione di base che usa i parametri definiti in connectorUIconfig:

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

Chiave API

Campo Obbligatorio Tipo Descrizione Valore predefinito
ApiKey Vero Stringa Chiave privata utente.
ApiKeyName Stringa Nome dell'intestazione URI che contiene il ApiKey valore. Authorization
ApiKeyIdentifier Stringa Valore stringa per anteporre il token. token
IsApiKeyInPostPayload Booleano Valore che determina se inviare il segreto nel corpo anziché nell'intestazione POST . false

APIKey esempi di autenticazione:

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

Il risultato di questo esempio è il segreto definito dall'input dell'utente inviato nell'intestazione seguente: X-MyApp-Auth-HeaderBearer apikey.

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

In questo esempio vengono usati i valori predefiniti e viene restituita l'intestazione seguente: Authorizationtoken 123123123.

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

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

OAuth2

Codeless Connector Framework supporta la concessione del codice di autorizzazione OAuth 2.0 e le credenziali client. Il tipo di concessione codice di autorizzazione viene usato dai client riservati e pubblici per scambiare un codice di autorizzazione con 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 Obbligatorio Tipo Descrizione
ClientId Vero. Stringa ID client.
ClientSecret Vero. Stringa Segreto client.
AuthorizationCode True quando il grantType valore è authorization_code. Stringa Se il tipo di concessione è authorization_code, questo valore di campo è il codice di autorizzazione restituito dal server di autenticazione.
Scope True per il authorization_code tipo di concessione.
Facoltativo per il client_credentials tipo di concessione.		 Stringa Elenco di ambiti separati da spazi per il consenso dell'utente. Per altre informazioni, vedere Ambiti e autorizzazioni OAuth2.
RedirectUri True quando il grantType valore è authorization_code. Stringa L'URL per il reindirizzamento deve essere https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights.
GrantType Vero. Stringa Tipo di concessione. Può essere authorization_code o client_credentials.
TokenEndpoint Vero. Stringa URL per lo scambio di codice con un token valido nella authorization_code concessione o un ID client e un segreto con un token valido nella client_credentials concessione.
TokenEndpointHeaders Oggetto Oggetto chiave/valore facoltativo per inviare intestazioni personalizzate al server token.
TokenEndpointQueryParameters Oggetto Oggetto chiave/valore facoltativo per inviare parametri di query personalizzati al server token.
AuthorizationEndpoint Vero. Stringa URL per il consenso dell'utente per il authorization_code flusso.
AuthorizationEndpointHeaders Oggetto Oggetto chiave/valore facoltativo per inviare intestazioni personalizzate al server di autenticazione.
AuthorizationEndpointQueryParameters Oggetto Coppia chiave/valore facoltativa usata in una richiesta di flusso del codice di autorizzazione OAuth2.

È possibile usare il flusso di codice di autenticazione per recuperare i dati per conto delle autorizzazioni di un utente. È possibile usare le credenziali client per recuperare i dati con le 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 token.

Ecco un esempio del 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"
}

Ecco un esempio del 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

L'autenticazione JSON Web Token (JWT) supporta il recupero di token tramite le credenziali di nome utente e password e l'uso di tali token per le richieste API.

Esempio di base
"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password", 
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://token_endpoint.contoso.com",
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}
Credenziali nel corpo POST (impostazione predefinita)
"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "username",
        "value": "[[parameters('UserName')]"
    },
    "password": {
        "key": "password",
        "value": "[[parameters('Password')]"
    },
    "TokenEndpoint": "https://api.example.com/token",
    "Headers": {
        "Accept": "application/json",
        "Content-Type": "application/json"
    },
    "IsCredentialsInHeaders": false,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token"
}
Credenziali nelle intestazioni (autenticazione di base)
"auth": {
    "type": "JwtToken",
    "userName": {
        "key": "client_id",
        "value": "[[parameters('ClientId')]"
    },
    "password": {
        "key": "client_secret",
        "value": "[[parameters('ClientSecret')]"
    },
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "IsCredentialsInHeaders": true,
    "IsJsonRequest": true,
    "JwtTokenJsonPath": "$.access_token",
    "RequestTimeoutInSeconds": 30
}
Credenziali nelle intestazioni (token utente)
"auth": {
    "type": "JwtToken",
    "UserToken": "[[parameters('userToken')]",
    "UserTokenPrepend": "Bearer",
    "TokenEndpoint": "https://api.example.com/oauth/token",
    "Headers": {
        "Accept": "application/json"
    },
    "TokenEndpointHttpMethod": "GET",
    "NoAccessTokenPrepend": true,
    "JwtTokenJsonPath": "$.systemToken"
}

Seguire questo flusso di autenticazione:

  1. Inviare credenziali a TokenEndpoint per ottenere il token JWT, quando si usa userName e password, IsCredentialsInHeaders viene usato per determinare dove inserire le credenziali nella richiesta.

    • Se IsCredentialsInHeaders: true: invia un'intestazione di autenticazione di base con username:password.
    • Se IsCredentialsInHeaders: false: invia le credenziali in un POST corpo.

  2. Estrarre il token usando JwtTokenJsonPath o dall'intestazione della risposta.

  3. L'intestazione Authorization per i token JWT è una costante e sarà sempre "Authorization".

Campo Obbligatorio Tipo Descrizione
type Vero Stringa Tipo. Deve essere JwtToken
userName True (se userToken non viene usato) Oggetto Coppia chiave/valore per le userName credenziali. Se userName e password vengono inviati nella richiesta di intestazione, specificare la value proprietà con il nome utente. Se userName e password vengono inviati nella richiesta del corpo, specificare Key e Value.
password True (se userToken non viene usato) Oggetto Coppia chiave/valore per le credenziali della password. Se userName e password vengono inviati nella richiesta di intestazione, specificare la value proprietà con .userName Se userName e password vengono inviati nella richiesta del corpo, specificare Key e Value.
userToken True (se userName non viene usato) Stringa Token utente generato dal client per ottenere il token di sistema per l'autenticazione.
UserTokenPrepend Falso Stringa Valore che indica se anteporre il testo prima del token. Impostazione predefinita: Bearer.
NoAccessTokenPrepend Falso Booleano Flag di accesso che indica che il token non deve anteporre nulla.
TokenEndpointHttpMethod Falso Stringa Metodo HTTP per l'endpoint del token. Può essere Get o Post. Il valore predefinito è Post.
TokenEndpoint Vero Stringa Endpoint URL usato per ottenere il token JWT.
IsCredentialsInHeaders Booleano Valore che indica se inviare le credenziali come intestazione di autenticazione di base (true) rispetto a un POST corpo (false), ignorato quando si usa userToken. Il valore predefinito è false.
IsJsonRequest Booleano Valore che indica se inviare la richiesta in JSON (intestazione Content-Type = application/json) rispetto alla codifica in formato (intestazione Content-Type = application/x-www-form-urlencoded). Il valore predefinito è false.
JwtTokenJsonPath Stringa Valore che indica il JSONPath valore da utilizzare per estrarre il token dalla risposta. Ad esempio: $.access_token.
JwtTokenInResponseHeader Booleano Valore che indica se estrarre il token dall'intestazione della risposta rispetto al corpo. Il valore predefinito è false.
JwtTokenHeaderName. Stringa Valore che indica il nome dell'intestazione quando il token si trova nell'intestazione della risposta. Il valore predefinito è Authorization.
JwtTokenIdentifier Stringa Identificatore usato per estrarre il token JWT da una stringa di token con prefisso.
QueryParameters Oggetto Parametri di query personalizzati da includere quando si invia la richiesta all'endpoint del token.
Headers Oggetto Intestazioni personalizzate da includere quando si invia la richiesta all'endpoint del token.
RequestTimeoutInSeconds Numero intero Timeout della richiesta in secondi. Il valore predefinito è 100, con un valore massimo di 180.

Nota

Limitazioni

  • Richiede l'autenticazione con nome utente e password per l'acquisizione di token
  • Non supporta le richieste di token basate su chiave API
  • Non supporta l'autenticazione personalizzata dell'intestazione (senza nome utente e password)

Configurazione della richiesta

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

Campo Obbligatorio Tipo Descrizione
ApiEndpoint Vero. Stringa Questo campo determina l'URL per il server remoto e definisce l'endpoint da cui eseguire il pull dei dati.
RateLimitQPS Numero intero Questo campo definisce il numero di chiamate o query consentite in un secondo per la richiesta iniziale. Non si applica alle richieste impaginate. Per limitare la paginazione, impostare PaginatedCallsPerSecondanche .
PaginatedCallsPerSecond Double (0...1000) Questo campo definisce il numero di chiamate al secondo consentite per le richieste impaginate all'API RESTful. Introduce un ritardo di (1000 / paginatedCallsPerSecond) millisecondi tra ogni chiamata API impaginata. Questa limitazione si applica solo alle richieste di impaginazione ed è separata da RateLimitQPS, che controlla la frequenza delle richieste iniziali. In genere, verrà impostato lo stesso valore RateLimitQPS di per rispettare il limite di frequenza dell'origine dati per tutte le richieste. 0 value indica che non viene applicata alcuna limitazione della paginazione.
RateLimitConfig Oggetto Questo campo definisce la configurazione del limite di frequenza per l'API RESTful. Per altre informazioni, vedere l'esempioRateLimitConfig.
QueryWindowInMin Numero intero Questo campo definisce la finestra di query disponibile in minuti. Il minimo è 1 minuto. Il valore predefinito è 5 minuti.
HttpMethod Stringa Questo campo definisce il metodo API: GET(impostazione predefinita) o POST.
QueryTimeFormat Stringa Questo campo definisce il formato di data e ora previsto dall'endpoint (server remoto). Il CCF usa la data e l'ora correnti ovunque venga usata questa variabile. I valori possibili sono le costanti , UnixTimestampUnixTimestampInMillso 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) Questo campo definisce che i valori di 1 per 6 i tentativi possono essere ripristinati da un errore. Il valore predefinito è 3.
TimeoutInSeconds Intero (1...180) Questo campo definisce il timeout della richiesta in secondi. Il valore predefinito è 20.
IsPostPayloadJson Booleano Questo campo determina se il POST payload è in formato JSON. Il valore predefinito è false.
Headers Oggetto Questo campo include coppie chiave/valore che definiscono le intestazioni della richiesta.
QueryParameters Oggetto Questo campo include coppie chiave/valore che definiscono i parametri della query di richiesta.
StartTimeAttributeName True quando il EndTimeAttributeName valore è impostato. Stringa Questo campo definisce il nome del parametro di query per l'ora di inizio della query. Per altre informazioni, vedere l'esempioStartTimeAttributeName.
EndTimeAttributeName True quando StartTimeAttributeName è impostato. Stringa Questo campo definisce il nome del parametro di query per l'ora di fine della query.
QueryTimeIntervalAttributeName Stringa Questo campo viene usato se l'endpoint richiede un formato specializzato per eseguire query sui dati in un intervallo di tempo. Utilizzare questa proprietà con i QueryTimeIntervalPrepend parametri e QueryTimeIntervalDelimiter . Per altre informazioni, vedere l'esempioQueryTimeIntervalAttributeName.
QueryTimeIntervalPrepend True quando QueryTimeIntervalAttributeName è impostato. Stringa Riferimento QueryTimeIntervalAttributeNamea .
QueryTimeIntervalDelimiter True quando QueryTimeIntervalAttributeName è impostato. Stringa Riferimento QueryTimeIntervalAttributeNamea .
QueryParametersTemplate Stringa Questo campo fa riferimento al modello di query da usare quando si passano parametri in scenari avanzati.

Ad esempio: "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}".
InitialCheckpointTimeUtc DateTime (UTC) Specifica l'ora di inizio della query per il primo polling quando non esiste alcun checkpoint archiviato. Quando un checkpoint viene salvato in modo permanente dopo il primo polling riuscito, questo valore viene ignorato. Questa impostazione ha effetto solo quando la configurazione della richiesta del connettore definisce un parametro di query dell'ora di inizio (ad startTimeAttributeName esempio o il {_QueryWindowStartTime} token di sostituzione) senza un parametro di fine corrispondente. Non ha alcun effetto sui connettori che si basano esclusivamente su cursori di impaginazione o token. Formato: ISO 8601 UTC datetime (ad esempio, 2024-01-15T00:00:00Z).

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

Variabile predefinita Per l'uso in queryParameters Per l'uso in queryParametersTemplate
_QueryWindowStartTime Sì Sì
_QueryWindowEndTime Sì Sì
_APIKeyName No Sì
_APIKey No Sì

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

Esempio di RateLimitConfig

Si consideri questo esempio:

ApiEndpoint = https://www.example.com.

"rateLimitConfig": {
  "evaluation": {
    "checkMode": "OnlyWhen429"
  },
  "extraction": {
    "source": "CustomHeaders",
    "headers": {
      "limit": {
        "name": "X-RateLimit-Limit",
        "format": "Integer"
      },
      "remaining": {
        "name": "X-RateLimit-Remaining",
        "format": "Integer"
      },
      "reset": {
        "name": "X-RateLimit-RetryAfter",
        "format": "UnixTimeSeconds"
      }
    }
  },
  "retryStrategy": {
    "useResetOrRetryAfterHeaders": true
  }
}

Quando la risposta include intestazioni di limite di frequenza, il connettore può usare queste informazioni per modificare la frequenza delle richieste.

Esempi di richieste che usano Microsoft Graph come API dell'origine dati

Questo esempio esegue query sui messaggi con un parametro di query di filtro. Per altre informazioni, vedere Parametri di query di Microsoft API 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 "
}

L'esempio precedente invia 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.

Con questo esempio si ottengono gli stessi risultati:

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

È disponibile un'altra opzione per le situazioni in cui l'origine dati prevede due 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",
}

Questa opzione invia 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 query complesse, usare QueryParametersTemplate. Questo esempio invia una POST richiesta con parametri nel corpo:

"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 il modo in cui il connettore dati gestisce le risposte usando i parametri seguenti:

Campo Obbligatorio Tipo Descrizione
EventsJsonPaths Vero Elenco di stringhe Definisce il percorso del messaggio nella risposta JSON. Un'espressione di percorso JSON specifica un percorso di un elemento, o un set di elementi, in una struttura JSON.
SuccessStatusJsonPath Stringa Definisce il percorso del messaggio di esito positivo nella risposta JSON. Quando questo parametro è definito, deve essere definito anche il SuccessStatusValue parametro .
SuccessStatusValue Stringa Definisce il percorso del valore del messaggio di esito positivo nel codice JSON della risposta.
IsGzipCompressed Booleano Determina se la risposta è compressa in un file GZIP.
format Vero Stringa Determina se il formato è json, csvo xml.
CompressionAlgo Stringa Definisce l'algoritmo di compressione, multi-gzip o deflate. Per l'algoritmo di compressione GZIP, configurare IsGzipCompressed su True anziché impostare un valore per questo parametro.
CsvDelimiter Stringa Fa riferimento se il formato della risposta è CSV e si vuole modificare il delimitatore CSV predefinito di ",".
HasCsvBoundary Booleano Indica se i dati CSV hanno un limite.
HasCsvHeader Booleano Indica se i dati CSV hanno un'intestazione. Il valore predefinito è True.
CsvEscape Stringa Definisce un carattere di escape per un limite di campo. Il valore predefinito è "

Ad esempio, un 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 Fa riferimento a un caso speciale in cui il server remoto restituisce un oggetto anziché un elenco di eventi in cui ogni proprietà include dati.

Nota

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

Esempi di configurazione della risposta

È prevista una risposta del server in formato JSON. La risposta include i dati richiesti nel valore della proprietà. Lo stato della proprietà della 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 si prepara per un 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 CCF deve sapere come ricevere parti dei dati nelle pagine di risposta. I tipi di paging tra cui scegliere sono:

Tipo di paging Fattore decisionale
La risposta API contiene collegamenti alle pagine successive e precedenti?
La risposta API ha un token o un cursore per le pagine successive e precedenti?
La risposta API supporta un parametro per il numero di oggetti da ignorare durante il paging?
La risposta API supporta un parametro per il numero di oggetti da restituire?

Configurare LinkHeader o PersistentLinkHeader

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

LinkHeader paging significa che la risposta API include:

  • Intestazione della Link risposta HTTP.
  • Percorso JSON per recuperare il collegamento dal corpo della risposta.

PersistentLinkHeaderIl paging di tipo ha le stesse proprietà di LinkHeader, ad eccezione del fatto che l'intestazione del collegamento persiste nell'archiviazione back-end. Questa opzione abilita i collegamenti di paging tra le finestre di query.

Ad esempio, alcune API non supportano l'ora di inizio o l'ora di fine delle query. Supportano invece un cursore sul lato server. È possibile usare i tipi di pagina persistenti 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. Questo problema potrebbe influire sulla latenza.

Campo Obbligatorio Tipo Descrizione
LinkHeaderTokenJsonPath Falso Stringa 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}]}, il LinkHeaderTokenJsonPath valore è $.nextPage.
PageSize Falso Numero intero Utilizzare questa proprietà per determinare il numero di eventi per pagina.
PageSizeParameterName Falso Stringa Usare questo nome del parametro di query per indicare le dimensioni della pagina.
PagingInfoPlacement Falso Stringa Utilizzare questa proprietà per determinare come vengono popolate le informazioni di paging. QueryString Accetta o RequestBody.
PagingQueryParamOnly Falso Booleano Utilizzare questa proprietà per specificare i parametri di query. Se impostato su true, omette tutti gli altri parametri di query tranne i parametri di query di paging.

Ecco alcuni esempi:

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

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

Configurare NextPageUrl

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

Campo Obbligatorio Tipo Descrizione
PageSize Falso Numero intero Numero di eventi per pagina.
PageSizeParameterName Falso Stringa Nome del parametro di query per le dimensioni della pagina.
NextPageUrl Falso Stringa Campo usato solo se il connettore è per l'API Coralogix.
NextPageUrlQueryParameters Falso Oggetto Coppie chiave/valore che aggiungono un parametro di query personalizzato a ogni richiesta per la pagina successiva.
NextPageParaName Falso Stringa Nome della pagina successiva nella richiesta.
HasNextFlagJsonPath Falso Stringa Percorso dell'attributo flag HasNextPage .
NextPageRequestHeader Falso Stringa Nome dell'intestazione di pagina successiva nella richiesta.
NextPageUrlQueryParametersTemplate Falso Stringa Campo usato solo se il connettore è per l'API Coralogix.
PagingInfoPlacement Falso Stringa Campo che determina la modalità di popolamento delle informazioni di paging. QueryString Accetta o RequestBody.
PagingQueryParamOnly Falso Booleano Campo che determina i parametri di query. Se impostato su true, omette tutti gli altri parametri di query tranne i parametri di query di paging.

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-type pagination usa un token (un hash o un cursore) che rappresenta lo stato della pagina corrente. Il token è incluso nella risposta 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 ricorda l'ultimo token recuperato dal client e fornisce il token successivo nelle richieste successive. Il client continua da dove si è interrotto, anche se effettua nuove richieste in un secondo momento.

Campo Obbligatorio Tipo Descrizione
PageSize Falso Numero intero Numero di eventi per pagina.
PageSizeParameterName Falso Stringa Nome del parametro di query per le dimensioni della pagina.
NextPageTokenJsonPath Falso Stringa Percorso JSON per il token di pagina successivo nel corpo della risposta.
NextPageTokenResponseHeader Falso Stringa Campo che specifica che se NextPageTokenJsonPath è vuoto, usare il token in questo nome di intestazione per la pagina successiva.
NextPageParaName Falso Stringa Campo che determina il nome della pagina successiva nella richiesta.
HasNextFlagJsonPath Falso Stringa Campo che definisce il percorso di un HasNextPage attributo flag quando si determina se nella risposta rimangono più pagine.
NextPageRequestHeader Falso Stringa Campo che determina il nome dell'intestazione di pagina successiva nella richiesta.
PagingInfoPlacement Falso Stringa Campo che determina la modalità di popolamento delle informazioni di paging. QueryString Accetta o RequestBody.
PagingQueryParamOnly Falso Booleano Campo che determina i parametri di query. Se impostato su true, omette tutti gli altri parametri di query tranne i parametri di query di paging.

Esempi:

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

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

Configurare l'offset

Offset-type pagination 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 Obbligatorio Tipo Descrizione
PageSize Falso Numero intero Numero di eventi per pagina.
PageSizeParameterName Falso Stringa Nome del parametro di query per le dimensioni della pagina.
OffsetParaName Falso Stringa Nome del parametro di query della richiesta successiva. Il CCF calcola il valore di offset per ogni richiesta (tutti gli eventi inseriti + 1).
PagingInfoPlacement Falso Stringa Campo che determina la modalità di popolamento delle informazioni di paging. QueryString Accetta o RequestBody.
PagingQueryParamOnly Falso Booleano Campo che determina i parametri di query. Se impostato su true, omette tutti gli altri parametri di query tranne i parametri di query di paging.

Esempio:

"paging": {
  "pagingType": "Offset", 
  "offsetParaName": "offset",
  "pageSize": 50,
  "pagingQueryParamOnly": true,
  "pagingInfoPlacement": "QueryString"
}

Configurare CountBasedPaging

CountBasedPaging-type pagination consente al client di specificare il numero di elementi da restituire nella risposta. Questa funzionalità è utile per le API che supportano la paginazione in base a un parametro count come parte del payload della risposta.

Campo Obbligatorio Tipo Descrizione
pageNumberParaName Vero Stringa Nome del parametro del numero di pagina nella richiesta HTTP.
PageSize Falso Numero intero Numero di eventi per pagina.
ZeroBasedIndexing Falso Booleano Flag che indica che il conteggio è in base zero.
HasNextFlagJsonPath Falso Stringa Percorso JSON del flag nel payload della risposta HTTP che indica che sono presenti più pagine.
TotalResultsJsonPath Falso Stringa Percorso JSON del numero totale di risultati nel payload della risposta HTTP.
PageNumberJsonPath Falso Stringa Percorso JSON del numero di pagina nel payload della risposta HTTP. Obbligatorio se totalResultsJsonPath specificato.
PageCountJsonPath Falso Stringa Percorso JSON del conteggio delle pagine nel payload della risposta HTTP. Obbligatorio se totalResultsJsonPath specificato.
PagingInfoPlacement Falso Stringa Campo che determina la modalità di popolamento delle informazioni di paging. QueryString Accetta o RequestBody.
PagingQueryParamOnly Falso Booleano Campo che determina i parametri di query. Se impostato su true, omette tutti gli altri parametri di query tranne i parametri di query di paging.

Esempio:

"paging": {
 "pagingType" : "CountBasedPaging", 
 "pageNumberParaName" : "page", 
 "pageSize" : 10, 
 "zeroBasedIndexing" : true, 
 "hasNextFlagJsonPath" : "$.hasNext", 
 "totalResultsJsonPath" : "$.totalResults", 
 "pageNumberJsonPath" : "$.pageNumber", 
 "pageCountJsonPath" : "$.pageCount"
}

Configurazione DCR

Campo Obbligatorio Tipo Descrizione
DataCollectionEndpoint Vero Stringa Endpoint di raccolta dati (DCE). Ad esempio: https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId Vero Stringa ID non modificabile DCR. Trovarlo visualizzando la risposta di creazione DCR o usando l'API DCR.
StreamName Vero Stringa Questo valore è definito streamDeclaration nel DCR. Il prefisso deve iniziare con Custom-.

Esempio di connettore dati CCF

Ecco un esempio di tutti i componenti del connettore dati CCF JSON:

{
   "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,
         "rateLimitConfig": {
            "evaluation": {
              "checkMode": "OnlyWhen429"
            },
            "extraction": {
              "source": "CustomHeaders",
              "headers": {
                "limit": {
                  "name": "X-RateLimit-Limit",
                  "format": "Integer"
                },
                "remaining": {
                  "name": "X-RateLimit-Remaining",
                  "format": "Integer"
                },
                "reset": {
                  "name": "X-RateLimit-RetryAfter",
                  "format": "UnixTimeSeconds"
                }
              }
            },
            "retryStrategy": {
              "useResetOrRetryAfterHeaders": true
            }
         },
         "queryWindowInMin": 5,
         "httpMethod": "POST",
         "queryTimeFormat": "UnixTimestamp",
         "startTimeAttributeName": "t0",
         "endTimeAttributeName": "t1",
         "retryCount": 3,
         "timeoutInSeconds": 60,
         "headers": {
            "Accept": "application/json",
            "User-Agent": "Example-app-agent"
         } 
      },
      "paging": {
         "pagingType": "LinkHeader",
         "pagingInfoPlacement": "RequestBody",
         "pagingQueryParamOnly": true
      },
      "response": {
         "eventsJsonPaths": ["$"]
      }
   }
}
  • Last updated on