Referência do conector de dados RestApiPoller para o Codeless Connector Framework

Pode criar um RestApiPoller conector de dados com o Codeless Connector Framework (CCF) ao utilizar este artigo como um suplemento à Microsoft Sentinel API REST para documentos de conectores de dados.

Cada conector de dados representa uma ligação específica de um conector de dados Microsoft Sentinel. Um conector de dados pode ter várias ligações, que obtêm dados de diferentes pontos finais. Pode concluir o modelo de implementação do conector de dados CCF com a configuração JSON que criar com este artigo.

Para obter mais informações, veja Criar um conector sem código para Microsoft Sentinel.

Criar ou atualizar conectores de dados

Localize a versão mais recente da API estável ou de pré-visualização ao referenciar as create operações ou update nos documentos da API REST. A diferença entre as create operações e update é que update requer o etag valor.

PUT método:

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

Parâmetros do URI

Para obter mais informações sobre a versão mais recente da API, veja Conectores de dados: criar ou atualizar parâmetros de URI.

Name Descrição
dataConnectorId O ID do conector de dados. Tem de ser um nome exclusivo que seja o mesmo que o name parâmetro no corpo do pedido.
resourceGroupName O nome do grupo de recursos, não sensível a maiúsculas e minúsculas.
subscriptionId O ID da subscrição de destino.
workspaceName O nome da área de trabalho, não o ID.
O padrão regex é ^[A-Za-z0-9][A-Za-z0-9-]+[A-Za-z0-9]$.
api-version A versão da API a utilizar para esta operação.

Corpo do pedido

O corpo do pedido para um RestApiPoller conector de dados CCF tem a seguinte estrutura:

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

RestApiPoller

RestApiPoller é um conector de dados CCF do poller de API que pode utilizar para personalizar payloads de paginação, autorização e pedido/resposta para a sua origem de dados.

Name Obrigatório Tipo Descrição
name Verdadeiro Cadeia O nome exclusivo da ligação que corresponde ao parâmetro URI.
kind Verdadeiro Cadeia O kind valor. Este campo tem de ser definido como RestApiPoller.
etag GUID O etag valor. Este campo tem de ficar vazio para a criação do novo conector. Para operações de atualização, etag tem de corresponder ao conector etag existente (GUID).
properties.connectorDefinitionName Cadeia O nome do DataConnectorDefinition recurso que define a configuração da IU do conector de dados. Para obter mais informações, aceda a Definição do conector de dados.
properties.auth Verdadeiro JSON Aninhado As propriedades de autenticação para consultar os dados. Para obter mais informações, aceda a Configuração de autenticação.
properties.request Verdadeiro JSON Aninhado O payload do pedido para consultar os dados, como o ponto final da API. Para obter mais informações, aceda a Pedir configuração.
properties. response Verdadeiro JSON Aninhado O objeto de resposta e a mensagem aninhada que a API devolve quando consulta os dados. Para obter mais informações, aceda a Configuração da resposta.
properties.paging JSON Aninhado O payload de paginação ao consultar os dados. Para obter mais informações, aceda a Configuração de paginação.
properties.dcrConfig JSON Aninhado Os parâmetros necessários quando os dados são enviados para uma regra de recolha de dados (DCR). Para obter mais informações, aceda a Configuração do DCR.

Configuração da autenticação

O CCF suporta os seguintes tipos de autenticação:

Nota

A implementação do CCF OAuth2 não suporta credenciais de certificado de cliente.

Como melhor prática, utilize parâmetros na secção de autenticação em vez de credenciais de hard-coding. Para obter mais informações, veja Proteger entradas confidenciais.

Para criar o modelo de implementação, que também utiliza parâmetros, tem de escapar aos parâmetros nesta secção com um início [adicional. Este passo permite que os parâmetros atribuam um valor com base na interação do utilizador com o conector. Para obter mais informações, veja Carateres de escape de expressões de modelo.

Para permitir que as credenciais sejam introduzidas a partir da IU, a connectorUIConfig secção requer que introduza os parâmetros pretendidos em instructions. Para obter mais informações, veja Referência de definições do conector de dados para o Codeless Connector Framework.

Autenticação básica

Campo Obrigatório Tipo
UserName Verdadeiro Cadeia
Password Verdadeiro Cadeia

Eis um exemplo de autenticação básica que utiliza parâmetros definidos no connectorUIconfig:

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

Chave de API

Campo Obrigatório Tipo Descrição Valor predefinido
ApiKey Verdadeiro Cadeia Chave secreta do utilizador.
ApiKeyName Cadeia Nome do cabeçalho do URI que contém o ApiKey valor. Authorization
ApiKeyIdentifier Cadeia Valor da cadeia para preparar o token. token
IsApiKeyInPostPayload Booleano Valor que determina se pretende enviar o segredo no POST corpo em vez do cabeçalho. false

APIKey exemplos de autenticação:

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

O resultado deste exemplo é o segredo definido a partir da entrada de utilizador enviada no seguinte cabeçalho: X-MyApp-Auth-Header: Bearer apikey.

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

Este exemplo utiliza os valores predefinidos e resulta no seguinte cabeçalho: Authorization: token 123123123.

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

Uma ApiKeyName vez que está explicitamente definido como "", o resultado é o seguinte cabeçalho: Authorization: 123123123.

OAuth2

O Codeless Connector Framework suporta a concessão de código de autorização OAuth 2.0 e as credenciais de cliente. O tipo de concessão do Código de Autorização é utilizado por clientes confidenciais e públicos para trocar um código de autorização por um token de acesso.

Depois de o utilizador regressar ao cliente através do URL de redirecionamento, a aplicação irá obter o código de autorização do URL e utilizá-lo para pedir um token de acesso.

Campo Obrigatório Tipo Descrição
ClientId É verdade. Cadeia O ID de cliente.
ClientSecret É verdade. Cadeia O segredo do cliente.
AuthorizationCode Verdadeiro quando o grantType valor é authorization_code. Cadeia Se o tipo de concessão for authorization_code, este valor de campo é o código de autorização devolvido pelo servidor de autenticação.
Scope Verdadeiro para o authorization_code tipo de concessão.
Opcional para o client_credentials tipo de concessão.		 Cadeia Uma lista separada por espaços de âmbitos para o consentimento do utilizador. Para obter mais informações, veja Âmbitos e permissões do OAuth2.
RedirectUri Verdadeiro quando o grantType valor é authorization_code. Cadeia O URL para redirecionamento tem de ser https://portal.azure.com/TokenAuthorize/ExtensionName/Microsoft_Azure_Security_Insights.
GrantType É verdade. Cadeia O tipo de concessão. Pode ser authorization_code ou client_credentials.
TokenEndpoint É verdade. Cadeia O URL para trocar código com um token válido na authorization_code concessão ou um ID de cliente e segredo com um token válido na client_credentials concessão.
TokenEndpointHeaders Objeto Um objeto de chave/valor opcional para enviar cabeçalhos personalizados para o servidor de tokens.
TokenEndpointQueryParameters Objeto Um objeto de chave/valor opcional para enviar parâmetros de consulta personalizados para o servidor de tokens.
AuthorizationEndpoint É verdade. Cadeia O URL do consentimento do utilizador para o authorization_code fluxo.
AuthorizationEndpointHeaders Objeto Um objeto de chave/valor opcional para enviar cabeçalhos personalizados para o servidor de autenticação.
AuthorizationEndpointQueryParameters Objeto Um par de chave/valor opcional utilizado num pedido de fluxo de código de autorização OAuth2.

Pode utilizar o fluxo de código de autenticação para obter dados em nome das permissões de um utilizador. Pode utilizar credenciais de cliente para obter dados com permissões de aplicação. O servidor de dados concede acesso à aplicação. Como não existe nenhum utilizador no fluxo de credenciais do cliente, não é necessário nenhum ponto final de autorização, apenas um ponto final de token.

Eis um exemplo do tipo de concessão 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"
}

Eis um exemplo do tipo de concessão 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

A autenticação JSON Web Token (JWT) suporta a obtenção de tokens através de credenciais de nome de utilizador e palavra-passe e a sua utilização para pedidos de API.

Exemplo básico
"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"
}
Credenciais no corpo POST (predefinição)
"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"
}
Credenciais nos cabeçalhos (autenticação básica)
"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
}
Credenciais nos cabeçalhos (token de utilizador)
"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"
}

Siga este fluxo de autenticação:

  1. Enviar credenciais para TokenEndpoint para obter o token JWT, ao utilizar userName e password, IsCredentialsInHeaders é utilizado para determinar onde colocar as credenciais no pedido.

    • Se IsCredentialsInHeaders: true: envia um cabeçalho de autenticação básico com username:password.
    • Se IsCredentialsInHeaders: false: envia credenciais num POST corpo.

  2. Extraia o token com JwtTokenJsonPath ou a partir do cabeçalho de resposta.

  3. O cabeçalho Autorização para os tokens JWT é uma constante e será sempre "Autorização".

Campo Obrigatório Tipo Descrição
type Verdadeiro Cadeia O tipo. Tem de ser JwtToken
userName Verdadeiro (se userToken não for utilizado) Objeto O par chave/valor da userName credencial. Se userName e password forem enviados no pedido de cabeçalho, especifique a value propriedade com o nome de utilizador. Se userName e password forem enviados no pedido do corpo, especifique Key e Value.
password Verdadeiro (se userToken não for utilizado) Objeto O par chave/valor da credencial da palavra-passe. Se userName e password forem enviados no pedido de cabeçalho, especifique a value propriedade com .userName Se userName e password forem enviados no pedido do corpo, especifique Key e Value.
userToken Verdadeiro (se userName não for utilizado) Cadeia O token de utilizador gerado pelo cliente para obter o token do sistema para autenticação.
UserTokenPrepend Falso Cadeia O valor que indica se pretende pré-acrescentar texto antes do token. Predefinição: Bearer.
NoAccessTokenPrepend Falso Booleano Um sinalizador de acesso que indica que o token não deve anexar nada.
TokenEndpointHttpMethod Falso Cadeia O método HTTP para o ponto final de token. Pode ser Get ou Post. A predefinição é Post.
TokenEndpoint Verdadeiro Cadeia O ponto final do URL utilizado para obter o token JWT.
IsCredentialsInHeaders Booleano O valor que indica se pretende enviar credenciais como um cabeçalho de autenticação básico (true) em comparação com um POST corpo (false), ignorado ao utilizar userToken. A predefinição é false.
IsJsonRequest Booleano O valor que indica se pretende enviar o pedido em JSON (cabeçalho Content-Type = application/json) em comparação com codificação de formulário (cabeçalho Content-Type = application/x-www-form-urlencoded). A predefinição é false.
JwtTokenJsonPath Cadeia O valor que indica o JSONPath valor a utilizar para extrair o token da resposta. Por exemplo: $.access_token.
JwtTokenInResponseHeader Booleano O valor que indica se pretende extrair o token do cabeçalho de resposta em comparação com o corpo. A predefinição é false.
JwtTokenHeaderName. Cadeia O valor que indica o nome do cabeçalho quando o token está no cabeçalho da resposta. A predefinição é Authorization.
JwtTokenIdentifier Cadeia O identificador utilizado para extrair o JWT de uma cadeia de tokens com prefixo.
QueryParameters Objeto Os parâmetros de consulta personalizados a incluir ao enviar o pedido para o ponto final do token.
Headers Objeto Os cabeçalhos personalizados a incluir ao enviar o pedido para o ponto final do token.
RequestTimeoutInSeconds Número inteiro O tempo limite do pedido em segundos. O valor predefinido é 100, com um valor máximo de 180.

Nota

Limitações

  • Requer autenticação de nome de utilizador e palavra-passe para a aquisição de tokens
  • Não suporta pedidos de tokens baseados em chaves da API
  • Não suporta a autenticação personalizada de cabeçalhos (sem nome de utilizador e palavra-passe)

Configuração do pedido

A secção de pedidos define a forma como o conector de dados CCF envia pedidos para a sua origem de dados (por exemplo, o ponto final da API e a frequência de consulta desse ponto final).

Campo Obrigatório Tipo Descrição
ApiEndpoint É verdade. Cadeia Este campo determina o URL do servidor remoto e define o ponto final a partir do qual pretende extrair dados.
RateLimitQPS Número inteiro Este campo define o número de chamadas ou consultas permitidas num segundo para o pedido inicial. Não se aplica a pedidos paginados. Para limitar a paginação, defina PaginatedCallsPerSecondtambém .
PaginatedCallsPerSecond Duplo (0...1000) Este campo define o número de chamadas por segundo permitido para pedidos paginados para a API RESTful. Introduz um atraso de (1000 / paginatedCallsPerSecond) milissegundos entre cada chamada à API paginada. Esta limitação aplica-se apenas a pedidos de paginação e é separada de RateLimitQPS, que controla a taxa de pedido inicial. Normalmente, este valor será definido como RateLimitQPS para respeitar o limite de taxa da origem de dados em todos os pedidos. 0 valor significa que não é aplicada nenhuma limitação de paginação.
RateLimitConfig Objeto Este campo define a configuração de limite de taxa para a API RESTful. Para obter mais informações, aceda a RateLimitConfig exemplo.
QueryWindowInMin Número inteiro Este campo define a janela de consulta disponível em minutos. O mínimo é de 1 minuto. A predefinição é 5 minutos.
HttpMethod Cadeia Este campo define o método da API: GET(predefinição) ou POST.
QueryTimeFormat Cadeia Este campo define o formato de data e hora que o ponto final (servidor remoto) espera. O CCF utiliza a data e hora atuais onde quer que esta variável seja utilizada. Os valores possíveis são as constantes: UnixTimestamp, UnixTimestampInMillsou qualquer outra representação válida da data e hora. Por exemplo: yyyy-MM-dd, MM/dd/yyyy HH:mm:ss.
A predefinição é ISO 8601 UTC.
RetryCount Número inteiro (1...6) Este campo define que os valores de 1 para 6 repetições têm permissão para recuperar de uma falha. O valor predefinido é 3.
TimeoutInSeconds Número inteiro (1...180) Este campo define o tempo limite do pedido em segundos. O valor predefinido é 20.
IsPostPayloadJson Booleano Este campo determina se o POST payload está no formato JSON. O valor predefinido é false.
Headers Objeto Este campo inclui pares chave/valor que definem os cabeçalhos do pedido.
QueryParameters Objeto Este campo inclui pares chave/valor que definem os parâmetros de consulta do pedido.
StartTimeAttributeName Verdadeiro quando o EndTimeAttributeName valor é definido. Cadeia Este campo define o nome do parâmetro de consulta para a hora de início da consulta. Para obter mais informações, aceda a StartTimeAttributeName exemplo.
EndTimeAttributeName Verdadeiro quando StartTimeAttributeName está definido. Cadeia Este campo define o nome do parâmetro de consulta para a hora de fim da consulta.
QueryTimeIntervalAttributeName Cadeia Este campo é utilizado se o ponto final necessitar de um formato especializado para consultar os dados num período de tempo. Utilize esta propriedade com os QueryTimeIntervalPrepend parâmetros e QueryTimeIntervalDelimiter . Para obter mais informações, aceda a QueryTimeIntervalAttributeName exemplo.
QueryTimeIntervalPrepend Verdadeiro quando QueryTimeIntervalAttributeName está definido. Cadeia Referência QueryTimeIntervalAttributeName.
QueryTimeIntervalDelimiter Verdadeiro quando QueryTimeIntervalAttributeName está definido. Cadeia Referência QueryTimeIntervalAttributeName.
QueryParametersTemplate Cadeia Este campo referencia o modelo de consulta a utilizar ao transmitir parâmetros em cenários avançados.

Por exemplo: "queryParametersTemplate": "{'cid': 1234567, 'cmd': 'reporting', 'format': 'siem', 'data': { 'from': '{_QueryWindowStartTime}', 'to': '{_QueryWindowEndTime}'}, '{_APIKeyName}': '{_APIKey}'}".
InitialCheckpointTimeUtc DateTime (UTC) Especifica a hora de início da consulta para o primeiro inquérito quando não existe nenhum ponto de verificação armazenado. Depois de um ponto de verificação persistir após a primeira sondagem com êxito, este valor é ignorado. Esta definição só entra em vigor quando a configuração do pedido do conector define um parâmetro de consulta de hora de início (como startTimeAttributeName ou o {_QueryWindowStartTime} token de substituição) sem um parâmetro de hora de fim correspondente. Não tem qualquer efeito nos conectores que dependem apenas de cursores ou tokens de paginação. Formato: ISO 8601 UTC datetime (por exemplo, 2024-01-15T00:00:00Z).

Quando a API exigir parâmetros complexos, utilize queryParameters ou queryParametersTemplate. Estes comandos incluem algumas variáveis incorporadas.

Variável incorporada Para utilização em queryParameters Para utilização em queryParametersTemplate
_QueryWindowStartTime Sim Sim
_QueryWindowEndTime Sim Sim
_APIKeyName Não Sim
_APIKey Não Sim

Exemplo startTimeAttributeName

Considere este exemplo:

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

A consulta enviada para o servidor remoto é: https://www.example.com?from={QueryTimeFormat}&until={QueryTimeFormat + QueryWindowInMin}.

Exemplo de QueryTimeIntervalAttributeName

Considere este exemplo:

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

A consulta enviada para o servidor remoto é: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Exemplo de RateLimitConfig

Considere este exemplo:

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 a resposta inclui cabeçalhos de limite de taxa, o conector pode utilizar estas informações para ajustar a taxa de pedidos.

Pedir exemplos que utilizam o Microsoft Graph como a API de origem de dados

Este exemplo consulta mensagens com um parâmetro de consulta de filtro. Para obter mais informações, veja Parâmetros de consulta do Microsoft Graph API.

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

O exemplo anterior envia um GET pedido para https://graph.microsoft.com/v1.0/me/messages?filter=receivedDateTime gt {time of request} and receivedDateTime lt 2019-09-01T17:00:00.0000000. O carimbo de data/hora é atualizado para cada queryWindowInMin vez.

Obtém os mesmos resultados com este exemplo:

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

Existe outra opção para situações em que a origem de dados espera dois parâmetros de consulta (um para a hora de início e outro para a hora de fim).

Exemplo:

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

Esta opção envia um GET pedido para https://graph.microsoft.com/me/calendarView?startDateTime=2019-09-01T09:00:00.0000000&endDateTime=2019-09-01T17:00:00.0000000.

Para consultas complexas, utilize QueryParametersTemplate. Este exemplo envia um POST pedido com parâmetros no 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}))\"}"
}

Configuração da resposta

Defina a forma como o conector de dados processa as respostas com os seguintes parâmetros:

Campo Obrigatório Tipo Descrição
EventsJsonPaths Verdadeiro Lista de cadeias Define o caminho para a mensagem no JSON de resposta. Uma expressão de caminho JSON especifica um caminho para um elemento, ou um conjunto de elementos, numa estrutura JSON.
SuccessStatusJsonPath Cadeia Define o caminho para a mensagem de êxito no JSON de resposta. Quando este parâmetro é definido, o SuccessStatusValue parâmetro também deve ser definido.
SuccessStatusValue Cadeia Define o caminho para o valor da mensagem de êxito no JSON de resposta.
IsGzipCompressed Booleano Determina se a resposta é comprimida num ficheiro GZIP.
format Verdadeiro Cadeia Determina se o formato é json, csvou xml.
CompressionAlgo Cadeia Define o algoritmo de compressão ou multi-gzipdeflate. Para o algoritmo de compressão GZIP, configure IsGzipCompressed para True em vez de definir um valor para este parâmetro.
CsvDelimiter Cadeia Referências se o formato de resposta for CSV e quiser alterar o delimitador CSV predefinido de ",".
HasCsvBoundary Booleano Indica se os dados CSV têm um limite.
HasCsvHeader Booleano Indica se os dados CSV têm um cabeçalho. A predefinição é True.
CsvEscape Cadeia Define um caráter de escape para um limite de campo. A predefinição é "

Por exemplo, um CSV com cabeçalhos id,name,avg e uma linha de dados que contenham espaços como 1,"my name",5.5 requer o limite do " campo.
ConvertChildPropertiesToArray Booleano Referencia um caso especial em que o servidor remoto devolve um objeto em vez de uma lista de eventos em que cada propriedade inclui dados.

Nota

O tipo de formato CSV é analisado pela RFC4180 especificação.

Exemplos de configuração de resposta

Espera-se uma resposta do servidor no formato JSON. A resposta tem os dados pedidos no valor da propriedade. O estado da propriedade de resposta indica para ingerir os dados apenas se o valor for success.

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

A resposta esperada neste exemplo prepara-se para um CSV sem cabeçalho.

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

Configuração de paginação

Quando a origem de dados não consegue enviar todo o payload de resposta de uma só vez, o conector de dados CCF tem de saber como receber partes dos dados nas páginas de resposta. Os tipos de paginação à escolha são:

Tipo de paginação Fator de decisão
A resposta da API tem ligações para as páginas seguintes e anteriores?
A resposta da API tem um token ou cursor para as páginas seguintes e anteriores?
A resposta da API suporta um parâmetro para o número de objetos a ignorar ao paginar?
A resposta da API suporta um parâmetro para o número de objetos a devolver?

Configurar LinkHeader ou PersistentLinkHeader

O tipo de paginação mais comum é quando uma API de origem de dados do servidor fornece URLs para as páginas de dados seguintes e anteriores. Para obter mais informações sobre a especificação Do Cabeçalho da Ligação , consulte RFC 5988.

LinkHeader paginação significa que a resposta da API inclui:

  • O Link cabeçalho de resposta HTTP.
  • Um caminho JSON para obter a ligação a partir do corpo da resposta.

PersistentLinkHeaderA paginação -type tem as mesmas propriedades que LinkHeader, exceto que o cabeçalho da ligação persiste no armazenamento de back-end. Esta opção ativa ligações de paginação entre janelas de consulta.

Por exemplo, algumas APIs não suportam horas de início ou horas de fim da consulta. Em vez disso, suportam um cursor do lado do servidor. Pode utilizar tipos de página persistentes para memorizar o cursor do lado do servidor. Para obter mais informações, consulte O que é um cursor?.

Nota

Apenas uma consulta para o conector pode ser executada com PersistentLinkHeader para evitar condições de corrida no cursor do lado do servidor. Este problema pode afetar a latência.

Campo Obrigatório Tipo Descrição
LinkHeaderTokenJsonPath Falso Cadeia Utilize esta propriedade para indicar onde obter o valor no corpo da resposta.

Por exemplo, se a origem de dados devolver o seguinte JSON: { nextPage: "foo", value: [{data}]}, o LinkHeaderTokenJsonPath valor é $.nextPage.
PageSize Falso Número inteiro Utilize esta propriedade para determinar o número de eventos por página.
PageSizeParameterName Falso Cadeia Utilize este nome do parâmetro de consulta para indicar o tamanho da página.
PagingInfoPlacement Falso Cadeia Utilize esta propriedade para determinar como as informações de paginação são preenchidas. Aceita ou QueryStringRequestBody.
PagingQueryParamOnly Falso Booleano Utilize esta propriedade para especificar parâmetros de consulta. Se definido como verdadeiro, omite todos os outros parâmetros de consulta, exceto os parâmetros de consulta de paginação.

Eis alguns exemplos:

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

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

Configurar NextPageUrl

NextPageUrl-type paging means the API response includes a complex link in the response body similar to LinkHeader, but the URL is included in the response body instead of the header.

Campo Obrigatório Tipo Descrição
PageSize Falso Número inteiro O número de eventos por página.
PageSizeParameterName Falso Cadeia O nome do parâmetro de consulta para o tamanho da página.
NextPageUrl Falso Cadeia Campo utilizado apenas se o conector for para a API Coralogix.
NextPageUrlQueryParameters Falso Objeto Pares chave/valor que adicionam um parâmetro de consulta personalizado a cada pedido para a página seguinte.
NextPageParaName Falso Cadeia O nome da página seguinte no pedido.
HasNextFlagJsonPath Falso Cadeia O caminho para o atributo de HasNextPage sinalizador.
NextPageRequestHeader Falso Cadeia O nome do cabeçalho da página seguinte no pedido.
NextPageUrlQueryParametersTemplate Falso Cadeia Campo utilizado apenas se o conector for para a API Coralogix.
PagingInfoPlacement Falso Cadeia Campo que determina a forma como as informações de paginação são preenchidas. Aceita ou QueryStringRequestBody.
PagingQueryParamOnly Falso Booleano Campo que determina os parâmetros de consulta. Se definido como verdadeiro, omite todos os outros parâmetros de consulta, exceto os parâmetros de consulta de paginação.

Exemplo:

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

Configurar NextPageToken ou PersistentToken

NextPageToken-type pagination uses a token (a hash or a cursor) that represents the state of the current page. O token está incluído na resposta da API e o cliente acrescenta-o ao pedido seguinte para obter a página seguinte. Este método é frequentemente utilizado quando o servidor precisa de manter o estado exato entre os pedidos.

PersistentToken A paginação utiliza um token que persiste do lado do servidor. O servidor memoriza o último token que o cliente obteve e fornece o token seguinte nos pedidos subsequentes. O cliente continua onde ficou, mesmo que faça novos pedidos mais tarde.

Campo Obrigatório Tipo Descrição
PageSize Falso Número inteiro Número de eventos por página.
PageSizeParameterName Falso Cadeia Nome do parâmetro de consulta para o tamanho da página.
NextPageTokenJsonPath Falso Cadeia Caminho JSON para o token de página seguinte no corpo da resposta.
NextPageTokenResponseHeader Falso Cadeia Campo que especifica que, se NextPageTokenJsonPath estiver vazio, utilize o token neste nome de cabeçalho para a página seguinte.
NextPageParaName Falso Cadeia Campo que determina o nome da página seguinte no pedido.
HasNextFlagJsonPath Falso Cadeia Campo que define o caminho para um HasNextPage atributo de sinalizador ao determinar se restam mais páginas na resposta.
NextPageRequestHeader Falso Cadeia Campo que determina o nome do cabeçalho da página seguinte no pedido.
PagingInfoPlacement Falso Cadeia Campo que determina a forma como as informações de paginação são preenchidas. Aceita ou QueryStringRequestBody.
PagingQueryParamOnly Falso Booleano Campo que determina os parâmetros de consulta. Se definido como verdadeiro, omite todos os outros parâmetros de consulta, exceto os parâmetros de consulta de paginação.

Exemplos:

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

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

Configurar Desvio

Offset-type pagination specifies the number of pages to skip and a limit on the number of events to retrieve per page in the request. Os clientes obtêm um intervalo específico de itens do conjunto de dados.

Campo Obrigatório Tipo Descrição
PageSize Falso Número inteiro Número de eventos por página.
PageSizeParameterName Falso Cadeia Nome do parâmetro de consulta para o tamanho da página.
OffsetParaName Falso Cadeia O nome do parâmetro de consulta de pedido seguinte. O CCF calcula o valor de desvio para cada pedido (todos os eventos ingeridos + 1).
PagingInfoPlacement Falso Cadeia Campo que determina a forma como as informações de paginação são preenchidas. Aceita ou QueryStringRequestBody.
PagingQueryParamOnly Falso Booleano Campo que determina os parâmetros de consulta. Se definido como verdadeiro, omite todos os outros parâmetros de consulta, exceto os parâmetros de consulta de paginação.

Exemplo:

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

Configurar CountBasedPaging

CountBasedPagingA paginação -type permite ao cliente especificar o número de itens a devolver na resposta. Esta capacidade é útil para APIs que suportam a paginação com base num parâmetro de contagem como parte do payload de resposta.

Campo Obrigatório Tipo Descrição
pageNumberParaName Verdadeiro Cadeia Nome do parâmetro do número de página no pedido HTTP.
PageSize Falso Número inteiro Número de eventos por página.
ZeroBasedIndexing Falso Booleano Sinalizador que indica que a contagem é baseada em zero.
HasNextFlagJsonPath Falso Cadeia O caminho JSON do sinalizador no payload de resposta HTTP que indica que existem mais páginas.
TotalResultsJsonPath Falso Cadeia O caminho JSON do número total de resultados no payload de resposta HTTP.
PageNumberJsonPath Falso Cadeia O caminho JSON do número de página no payload de resposta HTTP. Necessário se totalResultsJsonPath for fornecido.
PageCountJsonPath Falso Cadeia O caminho JSON da contagem de páginas no payload de resposta HTTP. Necessário se totalResultsJsonPath for fornecido.
PagingInfoPlacement Falso Cadeia Campo que determina a forma como as informações de paginação são preenchidas. Aceita ou QueryStringRequestBody.
PagingQueryParamOnly Falso Booleano Campo que determina os parâmetros de consulta. Se definido como verdadeiro, omite todos os outros parâmetros de consulta, exceto os parâmetros de consulta de paginação.

Exemplo:

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

Configuração do DCR

Campo Obrigatório Tipo Descrição
DataCollectionEndpoint Verdadeiro Cadeia Ponto final de recolha de dados (DCE). Por exemplo: https://example.ingest.monitor.azure.com.
DataCollectionRuleImmutableId Verdadeiro Cadeia O ID imutável do DCR. Localize-a ao ver a resposta de criação do DCR ou através da API DCR.
StreamName Verdadeiro Cadeia Este valor é o streamDeclaration definido no DCR. O prefixo tem de começar por Custom-.

Conector de dados CCF de exemplo

Eis um exemplo de todos os componentes do JSON do conector de dados 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": ["$"]
      }
   }
}
  • Last updated on