Usando a API

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:

No Communications Mining™, os dados e fluxos de trabalho de desenvolvimento e produção podem ser separados tendo tenants separados ou colocando-os em projetos separados no mesmo tenant. Em cada caso, o acesso de dados é permissionado separadamente, para que os desenvolvedores possam ter acesso de administrador aos dados de desenvolvimento, enquanto controles mais rigorosos podem ser colocados na produção. Se estiver usando tenants separados, o ponto de extremidade da API será diferente para cada dado de desenvolvimento e produção; se estiver usando projetos separados no mesmo tenant, o ponto de extremidade desse único tenant será usado para ambos.

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 necessá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.