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

Criar novo conector

1. If you select Start from an API definition, you must provide the API definition:

   • 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. Selecione Continuar.

Configurar seu conector

1. In the Confirm import window, you can:

   • 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 the Search bar to look for a specific resource.

   • Selecione Criar.

     

2. The Settings window is now displayed.

3. In the Info tab you can configure the following fields:

   • Nome - Isso é refletido na chave do seu conector.
   • API type – This field is disabled by default, as only REST is currently supported.
   • Categorias - Você pode selecionar dentre as categorias disponíveis, como Inteligência artificial ou Marketing, ou criar a sua.
   • Description – Enter a description for your connector.
   • Ícone - selecione Pesquisar para carregar uma imagem do seu computador. Todos os tipos de imagem são compatíveis, mas recomendamos usar um SVG quadrado.

4. Catalog preview displays how your custom connector will appear in the Integration Service connector catalog.

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:

• Base URL – Automatically filled with the value declared at connector creation.

• 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 paginação, mantenha o valor padrão. Para obter detalhes, consulte a seção Paginação .

• Pagination max – Default value is 100. If the vendor documentation doesn’t provide any details on pagination, keep the default value.

• Cabeçalho do tipo conteúdo – Esse campo é 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 configurar as configurações de paginação no nível do conector em Configurações > API Base, definindo os campos Tipo de paginação e Máximo de paginação . 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 em 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áginas, conforme explicado em Como usar a 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 de página e por\_página .

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

• 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, page=1),
• Página começa com 0 refere-se à paginação em que a primeira página de resultados está no índice zero (por exemplo, page=0).

Configuração de recursos

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

1. Selecione seu recurso.
2. Selecione a aba 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 de paginação baseada em cursor no Connector Builder. A documentação de paginação Meta especifica onde, em cada solicitação, você encontra o token de próxima página e inclui uma referência direta ao token ou ao URL completo. 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 Meta Graph, o nome do token nextPage é depois e pageSize é limit.

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, então 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 de deslocamento usa números de registro para permitir a paginação por 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 Page e pageSize como parâmetros de paginação. Você pode substituí-las pelas especificações do provedor da seguinte maneira:

1. Selecione seu recurso.
2. Selecione a aba 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 o 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 de 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. ConsulteTipos de autenticação para obter mais informações sobre as opções suportadas.

Teste sua conexão

Once you have completed the authentication configuration, select Add connection from the drop-down menu:

If your connection is successful, the status is updated to Connected.

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. Selecione o menu Mais opções para configurar cada método. Você pode:

   • Add method – Opens the Create new resource window.

   • Allow method deletion – Activates a Delete icon for each resource in the group.

   • Edit path – Edit the resource’s path. For example: [BASE URL]/pet = https://petstore.swagger.io/v2/pet

   • Delete – Deletes a resource group. A message warns you that the operation cannot be undone.

   • 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 seguintes campos:

     • Path - [Base URL]/[path]

     • Nome de exibição

     • Select methods: Get, Get By Id, Post, Put, Patch, Delete

       

   • Do cURL: insira um comando cURL.

Configure seus recursos

Ao selecionar um recurso, a seguinte janela é exibida:

Depending on the resource method you select, the following configuration tabs are available: Parameters, Response/Request Fields, Pagination, Search.

Parâmetros

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

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.

The Pet object corresponds to the Pet resource group, and the available fields are the ones set for the GETBYID resource:

Campos de resposta e solicitação

Observação:

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

The Response and Request fields for each resource are automatically generated upon sending a request.

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

In the Response/Request fields tab, the following options are also available:

• Caixa de seleção Substituir ao enviar solicitação — se selecionada, quando você executa uma solicitação Enviar solicitação, a lista de campos é regenerada. Não selecione essa opção se você adicionou novos campos ao seu recurso.

• Additional options button:

  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.

• Add row button - Adds new fields to the resource.

Selecione o ícone Colunas visíveis para adicionar ou excluir colunas na tabela de campos.

Each color under the Methods column corresponds to a certain method: Get, Get by ID, Post, Put, Patch, Delete.

Paginação

Enable Pagination for a resource if you expect a list response. If you enable pagination, you also need to define the Response root key in the configuration tab, for nested lists.

Pesquisar

Activate the Enable Search checkbox to allow search setup for a resource.

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