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

Pode criar um conector de dados RestApiPoller com o Codeless Connector Framework (CCF) usando este artigo como complemento à API REST Microsoft Sentinel para data connectors docs.

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 conexões, que buscam dados de pontos de extremidade diferentes. Pode completar o modelo de implementação do conector de dados CCF usando a configuração JSON que constrói com este artigo.

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

Criação ou atualização de conectores de dados

Encontre a versão mais recente da API estável ou de pré-visualização consultando as create operações ou update na documentação 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 de URI

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

Corpo do pedido

O corpo da solicitação 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 de sondagem API que pode usar para personalizar payloads de paginação, autorização e pedido/resposta para a sua fonte de dados.

Configuração de autenticação

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

• Basic
• Chave de API
• OAuth2
• JWT

Como boa prática, use parâmetros na secção de autenticação em vez de codificar as credenciais de forma rígida. Para obter mais informações, consulte Proteger entrada confidencial.

Para criar o template de implementação, que também usa parâmetros, precisa de sair dos parâmetros nesta secção com um extra inicial [. Esta etapa permite que os parâmetros atribuam um valor com base na interação do utilizador com o conector. Para obter mais informações, consulte Caracteres de escape de expressões de modelo.

Para permitir a introdução das credenciais a partir da interface, a connectorUIConfig secção exige que introduza os parâmetros desejados em instructions. Para obter mais informações, consulte Referência de definições de conector de dados para o Codeless Connector Framework.

Autenticação básica

Aqui está um exemplo de autenticação básica que utiliza parâmetros definidos em connectorUIconfig:

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

chave de API

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 do utilizador enviada no seguinte cabeçalho: X-MyApp-Auth-Header: Bearer apikey.

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

Este exemplo usa os valores padrão e resulta no seguinte cabeçalho: Authorization: token 123123123.

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

Como ApiKeyName é 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 credenciais de cliente. O tipo de concessão de 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 que o usuário retornar ao cliente por meio da URL de redirecionamento, o aplicativo obterá o código de autorização da URL e o usará para solicitar um token de acesso.

Pode usar o fluxo de códigos de autenticação para obter dados em nome das permissões do utilizador. Pode usar as credenciais do cliente para obter dados com permissões de aplicação. O servidor de dados concede acesso ao aplicativo. Como não há utilizador no fluxo de credenciais do cliente, não é necessário um endpoint de autorização, apenas um endpoint de token.

Aqui está um exemplo do tipo de bolsa 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"
}

Aqui está um exemplo do tipo de bolsa 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 do POST (por defeito)

"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 em 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 em 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 obter o token JWT, ao usar userName e password, IsCredentialsInHeaders é usado para determinar onde colocar as credenciais no pedido.

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

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

3. O cabeçalho Authorization para os tokens JWT é constante e será sempre "Authorization".

Solicitar configuração

A secção de pedidos define como o conector de dados CCF envia pedidos para a sua fonte de dados (por exemplo, o endpoint da API e com que frequência deve sondar esse endpoint).

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

Exemplo de StartTimeAttributeName

Considere este exemplo:

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

A consulta enviada ao 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 ao servidor remoto é: https://www.example.com?interval=time:{QueryTimeFormat}..{QueryTimeFormat + QueryWindowInMin}.

Exemplo do 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 usar esta informação para ajustar a sua taxa de pedido.

Exemplos de pedidos que utilizam o Microsoft Graph como API de fonte de dados

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

"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 uma GET solicitação 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 temporal atualiza-se a cada queryWindowInMin vez.

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

Há outra opção para situações em que a fonte 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, use 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 de resposta

Defina como o seu conector de dados gere as respostas usando os seguintes parâmetros:

Exemplos de configuração de resposta

Espera-se uma resposta do servidor em formato JSON. A resposta tem os dados solicitados no valor da propriedade. O status da propriedade

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

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

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

Configuração de paginação

Quando a fonte de dados não pode enviar toda a carga útil de resposta de uma só vez, o conector de dados CCF precisa saber como receber partes dos dados nas páginas de resposta. Os tipos de paginação a escolher são:

Configurar LinkHeader ou PersistentLinkHeader

O tipo de paginação mais comum é quando uma API de fonte de dados do servidor fornece URLs para as páginas de dados seguintes e anteriores. Para mais informações sobre a especificação Link Header , veja RFC 5988.

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

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

PersistentLinkHeadera paginação de tipo -tem as mesmas propriedades que LinkHeader, exceto que o cabeçalho do link persiste no armazenamento de back-end. Esta opção permite links de paginação entre janelas de consulta.

Por exemplo, algumas APIs não suportam horários de início ou de término de consultas. Em vez disso, eles suportam um cursor do lado do servidor. Podes usar tipos de página persistentes para memorizar o cursor do lado do servidor. Para obter mais informações, consulte O que é um cursor?.

Seguem-se alguns exemplos:

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

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

Configurar NextPageUrl

NextPageUrlpaginação do tipo -significa que a resposta da API inclui uma ligação complexa no corpo da resposta semelhante a LinkHeader, mas a URL está incluída no corpo da resposta em vez do cabeçalho.

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

NextPageTokena paginação do tipo -usa um token (um hash ou cursor) que representa o estado da página atual. O token é incluído na resposta da API e o cliente adiciona-o ao próximo pedido para obter a página seguinte. Esse método é freqüentemente usado quando o servidor precisa manter o estado exato entre as solicitações.

PersistentToken A paginação usa um token que persiste no lado do servidor. O servidor lembra-se do último token que o cliente recuperou e fornece o token seguinte em pedidos subsequentes. O cliente continua de onde parou, mesmo que faça novos pedidos mais tarde.

Exemplos:

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

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

Configurar deslocamento

Offseta paginação do tipo -especifica o número de páginas a saltar e um limite para o número de eventos a recuperar por página no pedido. Os clientes buscam um intervalo específico de itens do conjunto de dados.

Exemplo:

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

Configurar CountBasedPaging

CountBasedPaginga paginação do tipo -permite ao cliente especificar o número de itens a devolver na resposta. Esta funcionalidade é útil para APIs que suportam paginação baseada num parâmetro de contagem como parte da carga útil de resposta.

Exemplo:

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

Configuração DCR

Exemplo de conector de dados CCF

Aqui está um exemplo de todos os componentes do conector de dados 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": ["$"]
      }
   }
}