Utilitários do Bridge: API de chamadas

O utilitário Call API permite que você gerencie as chamadas de API públicas que você faz em seus fluxos de trabalho de automação no Bridge. Ele tem dois componentes principais: 

• Perfis: retenha informações sobre as APIs do sistema às quais você deseja conectar seus fluxos de trabalho. 

• O módulo Make API Call usa dados de perfil e detalhes específicos que você fornece para fazer uma chamada de API para uma API do sistema.

  Essa configuração exige conhecimento sobre programação e sobre a API.

Dica do Bridge Builder

Os perfis simplificam as mudanças no fluxo de trabalho caso as principais informações sejam alteradas, como seu token de autorização ou o URL base. Uma atualização do perfil assegura que todos os módulos que chamarem esse perfil terão os dados mais recentes para fazer a chamada.

Criar módulo de chamada de API 

Esse é o único módulo no utilitário e contém os seguintes campos:

Endpoint

Esse campo especifica a ação que você deseja realizar (por exemplo, classificar a planilha). Nesse valor, você pode adicionar qualquer referência de dados dos gatilhos do Bridge. Aqui estão alguns exemplos de como configurar dados estáticos ou dinâmicos:

• Valor de ID estático — O formato de URL para esse tipo de dados é este: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Especifique o ID da planilha nesse URL, para que a chamada da API sempre classifique essa planilha específica. 
• Referência de dados do Dynamic Run Log — O formato de URL para esses dados é este: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. No entanto, em vez de adicionar o ID da planilha, você deve adicionar a referência de dados da planilha do Registro de Execução. É útil se o fluxo de trabalho do Bridge é acionado em alterações ou traz dados de várias planilhas. Quando você usa esse tipo de URL, a chamada da API classifica a planilha específica referenciada nesse URL.

Método

O método define o tipo de operações que você deseja fazer. Defina um método para cada chamada de API no módulo Make API Call. A maioria das APIs descreve o método necessário para um determinado ponto de extremidade da API. Por exemplo, com o Smartsheet, esses são os métodos que você pode usar:

• OBTENHA: inclua dados em seu fluxo de trabalho do Bridge “obtendo” uma linha de uma planilha.
• POST: Crie algo. Por exemplo, adicione uma linha a uma planilha.
• PUT: Atualize alguma coisa. Por exemplo, atualize uma linha em uma planilha.
• EXCLUIR: Exclua algo. Por exemplo, exclua uma linha em uma planilha.

Cabeçalhos

Os cabeçalhos são os valores necessários para a solicitação e os pares de valores-chave. Eles geralmente são usados para lidar com autorizações (permissões). Por exemplo, nas chamadas do Smartsheet, você teria um cabeçalho de chave chamado Autorização com o valor definido como Portador [Insira seu token de API].

O Perfil pode configurar os cabeçalhos necessários para cada chamada para um sistema. Em seu fluxo de trabalho, o módulo Make API Call permite que você configure cabeçalhos adicionais para ações específicas. 

Parâmetros do formulário 

Os parâmetros do formulário também são conhecidos como parâmetros ou argumentos de consulta. Os parâmetros do formulário são itens adicionais que você pode definir na solicitação. Você os define no módulo Make API Call.

Um exemplo de cenário seria aplicar a paginação às chamadas do Smartsheet para incluir alguns itens na resposta. Por exemplo, você deseja obter apenas a primeira página de um relatório com 20.000 linhas.

Corpo da solicitação HTTP

Um órgão tem os detalhes relevantes da solicitação que você deve enviar. Geralmente está no formato JSON.

O envio de parâmetros do formulário substitui quaisquer dados corporais.

Em uma chamada da API Sort Sheet, um corpo ficaria assim: {"sortCriteria”: [{"columnId”: {smartsheetColumnId}, “direction”: “DESCENDING"}]}. O corpo neste exemplo pode usar qualquer um desses tipos de valor:

• Um valor estático para uma coluna específica em uma planilha; ou
• Uma referência de dados dinâmica de Run Log em que o ID da coluna aparece. 

Um corpo pode não ser necessário dependendo do tipo de solicitação que você está fazendo. Por exemplo, você não precisa de um corpo para chamadas GET.

Saída

Se a API respondente enviar de volta um objeto JSON, ele será salvo no Run Log. Isso permite que você faça referência aos dados retornados posteriormente no fluxo de trabalho.

O que você precisa para começar

• Uma planilha 
  • O ID da planilha
  • Uma coluna que, quando alterada em suas linhas, aciona seu fluxo de trabalho do Bridge em
• Bridge
  • Integração do Smartsheet
  • Acionador do fluxo de trabalho do Bridge: Smartsheet - When Column Values are Changed
  • Módulo Bridge: Utilitários > API de chamada > Fazer chamada de API
• Uma chave de API do Smartsheet.

Para criar esse fluxo de trabalho no Bridge, autentique a integração do Smartsheet para sua área de trabalho do Bridge. 

Ao criar seu fluxo de trabalho, mantenha sua planilha, a documentação de API do Smartsheet e o fluxo de trabalho do Bridge abertos em três guias separadas. Isso facilitará a navegação durante o processo de criação.

Etapa 1: construir o modelo de fluxo de trabalho básico

Use todos os módulos necessários para o fluxo de trabalho. 

1. Crie um novo fluxo de trabalho no Bridge. 
2. No gerador de fluxo de trabalho, use o painel para adicionar o módulo Make API Call.
3. Salve o fluxo de trabalho.

Isso é o que você deve ver em seu fluxo de trabalho quando terminar: 

Brandfolder Image

Configurar o acionador do fluxo de trabalho

1. Selecione o módulo Trigger.
2. Na seção Integrações, selecione a Página de integrações.

3. Localize o Smartsheet na lista de integrações.

   Você pode usar a opção Conectado sob o logotipo do Bridge para obter uma lista somente das integrações autenticadas para esse espaço de trabalho.

4. Expanda a linha Triggers.
5. Para criar um novo acionador, selecione Adicionar aos acionadores.
6. Preencha os campos a seguir:
   • Nome do gatilho: crie um rótulo personalizado para seu gatilho.
   • ID da planilha: cole a ID da planilha (a planilha que você deseja classificar).
   • Tipo de evento: selecione quando os valores da coluna são alterados. 
   • Nome ou ID da coluna: digite o nome da coluna do Smartsheet à qual você deseja responder. Por exemplo, se você for classificar as linhas na planilha toda vez que a prioridade mudar, digite o nome da sua coluna prioritária.
   • Selecione Fluxo de trabalho: selecione o novo fluxo de trabalho que você acabou de criar na lista suspensa.
7. Selecione Salvar.
8. Copie o ID da coluna nas informações do gatilho. Depois de salvar o acionador do fluxo de trabalho, o ID da coluna fica disponível nas informações do acionador.
9. Cole no Bloco de notas ou em qualquer processador de texto. Você precisa do ID da coluna para uma etapa posterior. 
10. Retorne ao fluxo de trabalho.

Acesse os detalhes da chamada de API

Esse fluxo de trabalho altera o valor na coluna de prioridade do acionador da sua planilha. Depois que esse fluxo de trabalho detecta os acionadores, ele executa as ações necessárias na mesma planilha. Usamos as referências de dados de tempo de execução (Run Log) do gatilho para preencher os módulos do Smartsheet.

Para esse fluxo de trabalho, você deve fazer uma chamada de API para o endpoint do Smartsheet Sort Sheet. Use a documentação da API do Smartsheet para alterar o exemplo para cURL.

Etapa 2: configurar seu primeiro perfil

Os perfis são uma forma de salvar informações importantes para as APIs do sistema às quais você deseja conectar seus fluxos de trabalho. Quando você seleciona um perfil no módulo Fazer chamada de API, algumas das informações necessárias para fazer sua chamada de API já estão configuradas para você. 

1. Navegue até a guia Integrações.
2. Selecione o utilitário Call API.
3. Expanda a seção Perfis, na guia Perfis.

4. Selecione Adicionar aos perfis.

   Brandfolder Image

   
5. Dê um nome ao perfil. Cada nome de perfil deve ser único.
6. Adicione o URL básico da API do sistema à qual deseja se conectar.  O URL base do Smartsheet é https://api.smartsheet.com/2.0/
7. Em Cabeçalhos secretos, adicione quaisquer cabeçalhos que contenham tokens ou informações secretas, como tokens de API.
   • Por exemplo, nas chamadas do Smartsheet, você normalmente tem um cabeçalho de chave chamado Autorização com o valor definido como Portador [Insira seu token de API].
8. Em Cabeçalhos, adicione os cabeçalhos que devem ser incluídos em todas as chamadas de API que você fizer com esse perfil.
   • Neste exemplo, usamos Content-Type como cabeçalho com um valor definido como application/json.
9. Selecione Salvar.
10. Retorne ao fluxo de trabalho.

Dica do Bridge Builder

A URL base é a parte da URL da API do sistema que sempre permanece a mesma, não importa o que você esteja tentando fazer nesse sistema. O endpoint no módulo Make API Call permite que você inclua os detalhes e as ações específicas que você realiza com essa chamada de API.

Exemplo: estamos usando a API do Smartsheet para classificar uma planilha. A URL base para nosso perfil de API do Smartsheet é https://api.smartsheet.com/2.0 e a ação específica que estamos realizando com o módulo é classificar uma planilha específica, então devemos colocar sheets/sheet_id_or_data_reference_here/sort no campo Endpoint do módulo.

Etapa 3: configurar o módulo Make API Call em seu fluxo de trabalho

1. No módulo Make API Call, selecione o perfil de API desejado para usar no menu suspenso.
2. No campo Endpoint, inclua a parte do campo URL que não foi adicionada ao campo URL base no perfil.
   • Neste exemplo, usamos sheets/sheet_id_or_data_reference_here/sort.
3. Preencha os campos a seguir. Observe que você pode não usar todos eles:
   • Defina o Método como POST.
   • No campo Corpo da solicitação HTTP, um corpo ficaria assim: {"sortCriteria”: [{"columnId”: column_id_here, “direction”: “ASCENDING"}]}
   • Parâmetros do formulário (se estiver usando — não usando para este fluxo de trabalho)

4. Salve as alterações.

   Brandfolder Image

   

Etapa 4: testar o fluxo de trabalho

1. Abra sua planilha. 
2. Altere um valor em sua coluna de prioridade. 
3. Salve a planilha. 

Se sua coluna prioritária for suspensa, as linhas classificadas estarão em ordem crescente ou decrescente (dependendo do que você definiu no corpo da chamada de API) dos valores, conforme mostrados nas configurações da coluna. 

Configurações adicionais para o módulo

• O módulo Make API Call retorna todas as chamadas de API como um objeto JSON. Se você precisar que a resposta retorne como uma string, marque a caixa de seleção Retornar resposta bruta em Configurações adicionais no módulo.
• Se você precisar incluir cabeçalhos adicionais para uma chamada específica, copie-os na seção Cabeçalhos de Solicitação HTTP.

Opções alternativas para este fluxo de trabalho

• Acione a partir de uma pasta ou coluna diferente da que você deseja classificar. Isso exige que você altere os detalhes da chamada de API de acordo com a planilha e a coluna que você deseja classificar. 
• Adicione uma condição à sua classificação. Depois que o fluxo de trabalho for acionado, use um módulo de junção para avaliar o valor da coluna e realizar ações diferentes com base na alteração feita na coluna Prioridade (por exemplo: se a Prioridade for 0, mova a linha para fora da planilha e se a Prioridade for 1, classifique a planilha).
• Use um gatilho de agendamento. Ao usar esse gatilho, você não precisa responder às alterações, pois ele classifica a planilha uma vez por dia, semana ou mês.

Use as ferramentas da API Call em suas soluções

• Os perfis se aplicam à área de trabalho, portanto, todos os fluxos de trabalho em sua área de trabalho podem usar o mesmo perfil em qualquer módulo Make API Call (Fazer chamada API) usado.
• Quando os detalhes do perfil precisam mudar porque as permissões de um usuário foram alteradas ou a API do sistema faz alterações, há um único local para fazer esses ajustes e aplicá-los aos fluxos de trabalho no espaço de trabalho que estão usando esse perfil.
• Para cada API adicional do sistema à qual você precisa se conectar, você pode configurar um novo perfil exclusivo.
• O módulo Make API Call é bem-sucedido se receber qualquer resposta da API de destino, inclusive se receber um erro. Isso é útil em etapas posteriores para determinar caminhos em seu fluxo de trabalho para respostas inesperadas da API (por exemplo, se a chamada da API retornar um erro, você poderá enviar uma atualização para uma linha informando que houve um problema). Se você preferir que o fluxo de trabalho seja interrompido se a API retornar um erro, marque a caixa na seção Configurações adicionais do módulo.