Usando a API

Envie solicitações para a API do Communications Mining, abrangendo pontos de extremidade do tenant e autenticação com tokens de API de desenvolvedor ou credenciais do cliente OAuth.

Observação:

Nós nos esforçamos para tornar a API previsível, além de fácil de usar e integrar. Se você tiver algum feedback que possa nos ajudar a melhorá-la ou se você encontrar algum problema ou comportamento inesperado, entre em contato com o suporte. Vamos retornar o mais breve possível.

Ponto de Extremidade da API

Todas as solicitações de API são enviadas ao Communications Mining™ como objetos JSON para o seu endpoint do tenant por HTTPS.

Observação:

Você pode visualizar todos os pontos de extremidade disponíveis no. Além disso, você pode conferir o Tutorial da API.

Tenants integrados por meio da UiPath®:

https://cloud.uipath.com/<my_uipath_organisation>/<my_uipath_tenant>/reinfer_/api/...

Tenants integrados por meio do Communications Mining:

https://<mydomain>.reinfer.io/api/...

Importante:

In Communications Mining, development and production data and workflows can be separated either by having separate tenants, or by placing them in separate projects in the same tenant.

In each case the data access is permissioned separately, so that developers can have admin access to development data while stricter controls can be placed on production.

If you use separate tenants, the API endpoint is different for each of development and production data. If you use separate projects in the same tenant, that single tenant's endpoint is used for both.

Autenticação

Todas as solicitações de API exigem autenticação para identificar o usuário que faz a solicitação. Há suporte para dois métodos de autenticação: tokens de API de desenvolvedor e aplicativos externos (credenciais do cliente do OAuth).

Para obter o token de acesso de desenvolvedor, proceda da seguinte forma:

1. Acesse a Extração e Processamento Inteligente do Automation Cloud.

2. Acesse a página de Administração .

3. Selecione Minha conta.

4. Em Token de API, selecione o botão Regenerar , que gerará um token de acesso.

   

Observação:

Você pode ter apenas um token de API ativo por vez. Gerar um novo token invalidará o anterior.

Você precisa incluir o seguinte cabeçalho HTTP para cada chamada de API que você fizer, onde $REINFER_TOKEN é seu token de API do Communications Mining™.

Authorization: Bearer $REINFER_TOKEN

Os exemplos de bash pressupõem que você salvou seu token em uma variável de ambiente. Os exemplos de Python e Nó assumem que o token foi armazenado em uma variável local REINFER_TOKEN por meio de sua solução de configuração escolhida.

Bash

curl -X GET 'https://<my_api_endpoint>/api/...' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nó

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/...",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/...",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Resposta

{
  "status": "ok"
}

Autenticação com aplicativos externos

Para integrações automatizadas ou de servidor para servidor em que um token de API de desenvolvedor não é apropriado, você pode autenticar usando um aplicativo externo com o fluxo de Credenciais do cliente.

Etapa 1: Crie um aplicativo externo

Um administrador deve criar um aplicativo confidencial e configurar os escopos necessários com base em quais APIs você precisa acessar.

Escopos exigidos

• PM.User
• PM.User.Read
• Ixp.ApiAccess

Importante:

Salve o ID do aplicativo e o Segredo do aplicativo imediatamente após a criação, pois você não pode recuperar o segredo posteriormente.

Para as instruções completas, consulte Gerenciamento de aplicativos externos.

Etapa 2: atribuir permissões do aplicativo

Após criar o aplicativo externo, você deve atribuir a ele as permissões apropriadas antes que ele possa acessar recursos.

1. Navegue até a página Gerenciar acesso na IXP em seu ambiente UiPath.
2. Pesquise seu aplicativo pelo nome que você deu quando o criou.
3. Atribua as funções necessárias ao aplicativo. O aplicativo aparecerá na lista assim como usuários normais.
4. Salve as atribuições de função.

Para os detalhes completos da atribuição de permissão, consulte Gerenciamento de funções de usuário e grupos.

Etapa 3: autenticar usando o fluxo de credenciais do cliente

Use o tipo de concessão Credenciais do cliente para obter um token de acesso.

Parâmetros obrigatórios

• grant_type=client_credentials
• client_id={app_id} - a partir da Etapa 1
• client_secret={app_secret} - a partir da Etapa 1
• scope - os escopos que você configurou na Etapa 1 (separados por espaço)

Para os detalhes de autenticação completos, consulte Aplicativos externos (OAuth).

Etapa 4: usar o token de acesso

Depois de ter um token de acesso, inclua-o no cabeçalho Authorization para todas as solicitações de API.

Authorization: Bearer {access_token}

Exemplo de solicitação

curl -X GET "https://cloud.uipath.com/{organizationName}/{tenantName}/reinfer_/api/v1/datasets" \
  -H "Authorization: Bearer {access_token}" \
  -H "Accept: application/json"

Observação:

Substitua {organizationName}, {tenantName} e {access_token} por seus valores reais.

Permissões

Cada ponto de extremidade de API na lista suas permissões necessárias. Para visualizar as permissões que você tem, acesse a aba Gerenciar acesso na página Administração . A aba mostra os projetos aos quais você tem acesso e as permissões que você tem em cada projeto.

Erros

Usamos códigos de resposta HTTP condicionais para indicar o sucesso ou falha de uma solicitação de API. Em geral, os códigos no intervalo 2xx indicam sucesso, os códigos no intervalo 4xx indicam um erro que resultou da solicitação fornecida e os códigos no intervalo 5xx indicam um problema com o Communications Mining.

Solicitações desse erro também retornarão um corpo com um valor status de error, em vez de ok, e uma mensagem de erro descrevendo o erro.

Bash

curl -X GET 'https://<my_api_endpoint>/api/v1/nonexistent_page' \
    -H "Authorization: Bearer $REINFER_TOKEN"

Nó

const request = require("request");

request.get(
  {
    url: "https://<my_api_endpoint>/api/v1/nonexistent_page",
    headers: {
      Authorization: "Bearer " + process.env.REINFER_TOKEN,
    },
  },
  function (error, response, json) {
    // digest response
    console.log(JSON.stringify(json, null, 2));
  }
);

Python

import json
import os

import requests

response = requests.get(
    "https://<my_api_endpoint>/api/v1/nonexistent_page",
    headers={"Authorization": "Bearer " + os.environ["REINFER_TOKEN"]},
)

print(json.dumps(response.json(), indent=2, sort_keys=True))

Resposta

{
  "message": "404 Not Found",
  "status": "error"
}

Observação:

Sua solicitação pode falhar devido a problemas em sua rede antes de chegar ao Communications Mining. Em tais casos, a resposta que você recebe será diferente da resposta de erro do Communications Mining descrita anteriormente.

Tempo de desempenho

Usamos o cabeçalho HTTP Server-Timendo para comunicar o tempo necessário para que as solicitações para a nossa API sejam processadas. Incluímos uma única métrica, total, que você pode usar para medir quanto tempo nossa plataforma levou para processar sua solicitação sem a latência da solicitação de rede.

Um exemplo do cabeçalho como aparece em uma resposta:

Server-Timing: total;dur=37.7

Os valores Server-Timing são sempre em milissegundos, portanto, neste caso, a solicitação da API com este valor de cabeçalho levou 37,7 milissegundos para ser processada em nossa plataforma.