Informazioni di riferimento sul connettore dati RestApiPoller per il framework del connettore Codeless

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

Ogni connettore dati rappresenta un connettore dati specifico connection di un connettore dati Microsoft Sentinel. Un connettore dati potrebbe avere più connessioni, che recuperano i 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 dati: creare o aggiornare i parametri URI.

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

Configurazione dell'autenticazione

CCF supporta i tipi di autenticazione seguenti:

• Basic
• Chiave API
• OAuth2
• JWT

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 [. 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, è connectorUIConfig necessario immettere i parametri desiderati in instructions. Per altre informazioni, vedere Informazioni di riferimento sulle definizioni dei connettori dati per il framework del connettore codeless.

Autenticazione di base

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

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-Header. Bearer apikey

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

In questo esempio vengono usati i valori predefiniti e viene restituita l'intestazione seguente: Authorization: token 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 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.

È possibile usare il flusso del 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 del 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 l'acquisizione di token tramite credenziali di nome utente e password e l'uso 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 le credenziali a per TokenEndpoint ottenere il token JWT.

   • 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. Usare il token nelle richieste API successive con l'intestazione ApiKeyName .

Seguire questo flusso di autenticazione:

1. Inviare le credenziali a per TokenEndpoint ottenere il token JWT.

   • 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. Usare il token nelle richieste API successive con l'intestazione ApiKeyName .

   Nota

   Limitazioni

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

Richiedere la configurazione

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

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

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 header di limite di velocità, il connettore può utilizzare queste informazioni per regolare la sua velocità di richiesta.

Esempi di richiesta che usano Microsoft Graph come API di origine dati

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

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

Si ottengono gli stessi risultati 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}"
  }
}

Esiste 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 le 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:

Esempi di configurazione della risposta

È prevista una risposta del server in formato JSON. La risposta contiene i dati richiesti nel valore della proprietà. Lo stato della proprietà

"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 CCF deve sapere come ricevere parti dei dati nelle pagine di risposta. I tipi di paging tra cui scegliere sono:

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 collegamento , vedere RFC 5988.

LinkHeader il paging indica che la risposta dell'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 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. È possibile usare i tipi di pagina permanenti per ricordare il cursore sul lato server. Per altre informazioni, vedere Che cos'è un cursore?.

Di seguito sono riportati 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 dell'API include un collegamento complesso nel corpo della risposta simile a LinkHeader, ma l'URL è incluso nel corpo della risposta anziché nell'intestazione.

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

NextPageTokenLa paginazione -type 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.

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.

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 capacità è utile per le API che supportano la paginazione in base a un parametro count come parte del payload della risposta.

Esempio:

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

Configurazione di DCR

Connettore dati CCF di esempio

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

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