Como criar seu conector a partir de uma definição de API

Criar novo conector

1. Se você selecionar Iniciar a partir de uma definição de API, deverá fornecer a definição da API:

   • De um arquivo local - Carregue uma coleção do Postman ou Swagger.
   • De uma URL – Insira uma URL de arquivo, como https://petstore.swagger.io/v2/swagger.json.
     
     

     

     
     
2. Clique em Continuar.

Configurar seu conector

1. Na janela Confirmar importação, você pode:

   • Altere o Nome do provedor, Nome do aplicativo e Nome do conector.

   • Modifique os recursos que você deseja usar em seu conector personalizado. Todos os recursos disponíveis são habilitados automaticamente; e desabilite aquelas que você deseja excluir.

     • Use a barra Pesquisar para procurar um recurso específico.

   • Clique em Criar.
     
     

     

     
     
2. A janela Configurações agora é exibida.

3. Na guia Informações, você pode configurar os seguintes campos:

   • Nome — isso é refletido na chave do seu conector.
   • Tipo de API – Esse campo é desabilitado por padrão, pois, apenas REST é compatível no momento.
   • Categorias - Você pode selecionar entre as categorias disponíveis, como Inteligência artificial ou Marketing, ou criar a sua.
   • Descrição – Insira uma descrição para seu conector.
   • Ícone - Clique em Pesquisar para carregar uma imagem do seu computador. Todos os tipos de imagens são suportados, mas recomendamos usar um SVG quadrado.
4. Visualização do catálogo exibe como seu conector personalizado aparecerá no catálogo de conectores do Integration Service.
5. Selecione Salvar.

   
   

   

   
   

Configurar a API base

Na guia API Base , você configura o URL base para a API do aplicativo e a paginação:

• URL base — Preenchido automaticamente com o valor declarado na criação do conector.
• Tipo de paginação – As opções disponíveis no menu suspenso são: A página começa com 1, A página começa com 0, Deslocamento, Personalizado, Nenhum. Se a documentação do fornecedor não fornecer detalhes sobre a paginação, mantenha o valor padrão. Para obter mais detalhes, consulte a seção Paginação .
• Máx. de paginação — O valor padrão é 100. Se a documentação do fornecedor não mostrar detalhes sobre a paginação, mantenha o valor padrão.
• Cabeçalho do tipo conteúdo – Esse campo está desabilitado por padrão. Apenas application/json é compatível no momento.
• Aceitar cabeçalho – Esse campo é desabilitado por padrão. Apenas application/json é compatível no momento.
  
  

  

  
  

Paginação

A paginação permite que os aplicativos do fornecedor retornem partes de uma resposta incrementalmente, em vez de todas de uma vez, otimizando, assim, o tempo de resposta.

A paginação pode ser implementada de várias maneiras. Os conectores UiPath usam uma configuração de paginação padronizada, garantindo que todos os conectores operem da mesma maneira.

Você pode definir as configurações de paginação no nível do conector em Configurações > API base, definindo os campos Tipo de paginação e Paginação máxima . Para atividades baseadas em lista, você pode configurar ainda mais a paginação no nível do recurso.

Tipos de paginação

O campo Tipo de paginação oferece várias opções, para se alinhar com várias especificações do provedor:

• A página começa com 1

• As páginas começam com 0

• Deslocamento

• Cursor

• Nenhum

As atividades do conector personalizado funcionarão no seu ambiente do Studio, independentemente do tipo de Paginação selecionado. No entanto, para garantir que você receba respostas completas, é importante que você especifique e configure o tipo de paginação correto.

A página começa com 1 e a página começa com 0

Os tipos de paginação baseados em página dependem de parâmetros de consulta passados ao provedor para indicar qual página de resultados deve ser retornada e o número de resultados por página.

Por exemplo, o GitHub usa a paginação baseada em página, conforme explicado em Uso da paginação na API REST. Eles incluíram o URL da próxima página no cabeçalho de resposta para facilitar a implementação, mas o mecanismo subjacente é baseado nos parâmetros de consulta Page e per_page .

No Construtor de Conector, selecione uma das seguintes opções:

• A página começa com 1 refere-se à paginação em que a primeira página de resultados tem um índice de um (por exemplo, página=1),
• A página começa com 0 refere-se à paginação em que a primeira página de resultados está no índice de zero (por exemplo, página=0).

Configuração de recursos

Por padrão, a paginação baseada em página atribui Página e TamanhoDaPágina como os parâmetros de paginação. Você pode substituí-los por especificações do provedor da seguinte maneira:

1. Selecione seu recurso.
2. Selecione a guia Paginação .
3. Habilite a paginação e atualize os nomes de parâmetros para corresponder aos parâmetros do provedor.

Paginação do cursor

A paginação baseada em cursor depende de um token de página retornado do provedor em vez de uma página ou número de deslocamento que pode ser passado em chamadas subsequentes para retornar a próxima página de resultados.

Quando você faz uma solicitação no Connector Builder para um conector que usa a paginação baseada em cursor, os resultados retornados não são paginados automaticamente. Portanto, nem todos os resultados são retornados sem incluir manualmente o próximo cursor em uma chamada subsequente.

Semelhante a outros tipos de paginação, a paginação baseada em cursor geralmente inclui um valor para especificar o número de resultados por página.

Configuração de recursos

A paginação baseada em cursor fornece nomes padrão para o cursor e o tamanho da página (nextPage e pageSize) que você pode substituir para corresponder às especificações do provedor.

Identificação do caminho do token de página

O cursor da próxima página muitas vezes está aninhado nos campos de resposta da API. Portanto, é importante especificar o local do cursor no esquema de resposta para que o Integration Service possa extrair o valor do token da página e usá-lo em uma resposta subsequente.

Você pode especificar o local no campo de resposta da seguinte forma:

1. Identifique onde ele está localizado na resposta (corpo ou cabeçalho).

2. Identifique o caminho do campo com pontos separando cada nível.

Se o cursor estiver aninhado em um URL, você pode usar um símbolo de ponto de interrogação (?) para representar o parâmetro de consulta a ser extraído.

Exemplo

A API Meta Graph oferece um bom exemplo de uso da paginação baseada em cursor no Connector Builder. A documentação de Metapaginação especifica onde, em cada solicitação, você encontra o token da próxima página e inclui uma referência direta ao token ou à URL completa. Podemos usar esses exemplos para criar a paginação de recursos para a API do Meta Graph.

1. No recurso selecionado, atualize o nome do token NextPage e o nome PageSize para corresponder à API do provedor. De acordo com a documentação da API do Meta Graph, o nome do token nextPage é posterior e pageSize é limite.

2. Em seguida, identifique onde o token nextPage está disponível em cada solicitação. A documentação nos fornece esse JSON que mapeia os locais:

   {
     "data": [
        ... Endpoint data is here
     ],
     "paging": {
       "cursors": {
         "after": "MTAxNTExOTQ1MjAwNzI5NDE=",
         "before": "NDMyNzQyODI3OTQw"
       },
       "previous": "https://graph.facebook.com/{your-user-id}/albums?limit=25&before=NDMyNzQyODI3OTQw"
       "next": "https://graph.facebook.com/{your-user-id}/albums?limit=25&after=MTAxNTExOTQ1MjAwNzI5NDE="
     }
   }

Isso faz parte do corpo da resposta, portanto, você pode configurar o token nextPage de duas maneiras:

1. Mapa direto para o token da página (preferido): body.paging.cursors.after.
2. Use a próxima URL: body.paging.next?after.

Ambos os caminhos fornecem ao conector o local correto para recuperar o valor do token nextPage .

Paginação de deslocamento

A paginação deslocada usa números de registro para permitir a paginação em todos os objetos de resposta. O parâmetro Deslocamento especifica o número de itens a serem ignorados antes de começar a retornar resultados.

A paginação deslocada geralmente usa os dois parâmetros a seguir (os nomes exatos podem variar)

• Deslocamento - indica o registro para começar a retornar resultados.

• Limite - indica o número de resultados por página.

Configuração de recursos

Por padrão, a paginação baseada em página atribui Página e TamanhoDaPágina como os parâmetros de paginação. Você pode substituí-los por especificações do provedor da seguinte maneira:

1. Selecione seu recurso.
2. Selecione a guia Paginação .
3. Habilite a paginação e atualize os nomes de parâmetros para corresponder aos parâmetros do provedor.

Tipo de paginação Nenhum

Se a API do provedor não usar paginação, defina Tipo de paginação como Nenhum.

Configuração de recursos

Se você definir Tipo de paginação como Nenhum, a guia Paginação será removida dos recursos da atividade Listar .

Máx. de paginação

O campo Máx. de paginação refere-se ao número máximo de resultados que o provedor pode retornar.

O Integration Service tem um limite máximo de 2.000 resultados. Para melhorar a eficiência, recomendamos usar um número menor.

Definir o método de autenticação

Na guia Autenticação , você configura o tipo de autenticação para o seu conector. Consulte mais informações sobre as opções suportadas em Tipos de autenticação.

Teste sua conexão

Depois de concluir a configuração da autenticação, selecione Adicionar conexão no menu suspenso:

Se sua conexão for bem-sucedida, o status será atualizado para Conectado.

Recursos

O Construtor de Conector gera a lista de recursos com base na definição da API fornecida. O menu do lado esquerdo exibe a lista de recursos disponíveis, organizados em grupos.

1. Clique no link Mais opções para configurar cada método. Você pode:
   • Método Adicionar — Abre a janela Criar novo recurso .
   • Permitir exclusão do método - Ativa um ícone Excluir para cada recurso no grupo.
   • Editar caminho – Editar o caminho do recurso. Por exemplo: [BASE URL]/pet = https://petstore.swagger.io/v2/pet
   • Excluir - Exclui um grupo de recursos. Uma mensagem avisa que a operação não pode ser desfeita.
   • Duplicar - Abre a janela Duplicar recurso , onde você pode editar o caminho, escolher um nome de exibição e selecionar métodos.
     
     

     

     
     

2. Você também pode Criar novo grupo de recursos de duas maneiras:

   • Em branco: configure os campos a seguir:
     • Caminho - [Base URL]/[path]
     • Nome de exibição
     • Selecionar métodos: Obter, Obter por Id, Postar, Colocar, Patch, Excluir
       
       

       

       
       
   • Do cURL: insira um comando cURL.

Configure seus recursos

Ao selecionar um recurso, a seguinte janela é exibida:

Dependendo do método de recurso selecionado, as seguintes guias de configuração estarão disponíveis: Parâmetros, Campos de resposta/solicitação, Paginação, Pesquisa.

Parâmetros

Por exemplo, todas as quatro guias estão disponíveis para métodos GET. Para métodos POST, você só pode ver as guias Parâmetros, Campos de Solicitação e Campos de Resposta.

Em Parâmetros, você pode visualizar a lista de parâmetros disponíveis para o recurso selecionado, adicionar novos parâmetros ou importar parâmetros de um recurso existente.

Os parâmetros listados nesta tabela são aqueles que você usará no Studio ao construir automações usando seu conector personalizado.

O objeto Pet corresponde ao grupo de recursos Pet, e os campos disponíveis são aqueles definidos para o recurso GETBYID:

Campos de resposta e solicitação

Observação:

Objetos de matriz aninhada não são compatíveis no momento.

Os campos Resposta e Solicitação para cada recurso são gerados automaticamente quando uma solicitação é enviada.

Em cada guia respectiva, você pode editar ou excluir qualquer campo. Se você clicar no ícone Editar , a seguinte janela de configuração é exibida:

Na aba de campos de resposta/solicitação , as seguintes opções também estão disponíveis:

• Caixa de seleção Substituir ao enviar solicitação - Se estiver selecionada, ao executar um Enviar solicitação, a lista de campos é gerada novamente. Não selecione esta opção se você adicionou novos campos ao seu recurso.

• Botão de opções adicionais :

  Opção	O que faz
  Atualizar chave raiz de resposta	Defina a chave de resposta ao lidar com arrays aninhados na resposta.
  Excluir todos os campos do método	Exclui todos os campos para o método selecionado.
  Gerar a partir da carga	Use um exemplo de carga na documentação do serviço ou uma chamada de API para gerar os campos do recurso.

• Botão Adicionar linha - Adiciona novos campos ao recurso.

Clique no ícone Colunas visíveis para adicionar ou excluir colunas na tabela de campos.

Cada cor na coluna Métodos corresponde a um determinado método: Obter, Obter por ID, Postar, Colocar, Patch, Excluir.

Paginação

Habilite a paginação para um recurso se você espera uma resposta na forma de lista. Se habilitar a paginação, você também precisará definir a Chave raiz de resposta na guia de configuração, para listas aninhadas.

Pesquisar

Ative a caixa de seleção Habilitar pesquisa para permitir a configuração da pesquisa para um recurso.

Depois de configurar tudo o que precisa, você pode continuar com o .