Configurar a ferramenta Call API

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

A ferramenta Call API permite gerenciar chamadas públicas de API que você faz nos fluxos de trabalho de automação no Bridge. Ela tem dois componentes principais: 

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

• Módulo Make API Call: usa dados de perfil e detalhes específicos que você informa para fazer uma chamada a uma API do sistema.

   

Dica do gerador do Bridge

O Profiles também facilita a alteração de fluxos de trabalho usando esse perfil caso as principais informações sejam alteradas, como o token de autorização ou o URL básico. Se o perfil for atualizado, todos os módulos que o chamarem terão acesso aos dados mais recentes para fazer a chamada.

Campos de chamada de API

Antes de começarmos, vamos ver alguns detalhes de terminologia sobre o uso de APIs.

Base URL

Este campo está contido no perfil e é a parte do URL da API que permanece sempre a mesma. Para o Smartsheet, você usaria o URL básico: https://api.smartsheet.com/2.0/

Endpoint

Este campo está contido no módulo Make API Call e especifica a ação que você deseja realizar (por exemplo, classificar a planilha). Nesse URL, você pode adicionar eventuais referências de dados necessárias dos seus acionadores do Bridge.

Veja exemplos de como configurar dados estáticos ou dinâmicos:

• Valor de ID estático: o formato de URL para esse tipo de dado é este: https://api.smartsheet.com/2.0/sheets/{sheetId}/sort. Você precisa especificar o ID da planilha neste URL para que a chamada de API sempre classifique essa planilha específica. 
• Referência de dados dinâmica de Run Log: o formato de URL para estes dados é semelhante ao do valor de ID estático: https://api.smartsheet.com/2.0/sheets/{{sheetIddatareference}}/sort. No entanto, em vez de adicionar o ID da planilha, você precisaria adicionar a referência de dados da planilha do Run Log do fluxo de trabalho do Bridge. É útil se o fluxo de trabalho do Bridge é acionado em alterações ou traz dados de várias planilhas. Ao usar esse tipo de URL, a chamada de API classificará a planilha específica referenciada neste URL.

Method

O método define o tipo das operações que você está tentando fazer, e você o configurará 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, você usará os seguintes métodos:

• GET: traga dados para o fluxo de trabalho do Bridge “obtendo” uma linha de uma planilha.
• POST: crie algo. Por exemplo, adicione uma linha a uma planilha.
• PUT: atualize algo. Por exemplo, atualize uma linha em uma planilha.
• DELETE: exclua algo. Por exemplo, exclua uma linha em uma planilha.

Headers

Os headers (cabeçalhos) são os valores necessários para a solicitação e os pares chave-valor. Geralmente são usados para realizar autorizações (permissões). Por exemplo, nas chamadas do Smartsheet, você teria um Header de chave chamado Authorization com o valor definido como Bearer [insira o token de API].

É possível configurar no perfil os cabeçalhos que são necessários para cada chamada de um sistema. É possível configurar cabeçalhos adicionais para ações específicas no módulo Make API Call em seu fluxo de trabalho. 
 

Form Parameters 

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

Um caso de exemplo seria aplicar a paginação com chamadas do Smartsheet para que apenas um determinado número de itens seja incluído na resposta. Por exemplo, você deseja obter apenas a primeira página de um relatório com 20.000 linhas.
 

Body

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

O envio de Form Parameters substitui os dados de Body.

Em uma chamada de API de Sort Sheet, um corpo ficaria assim: {"sortCriteria": [{"columnId": {smartsheetcolumnID}, "direction": "DESCENDING"}]}. No exemplo acima, o corpo poderia usar um destes 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. 

Dependendo do tipo de pedido que você está fazendo, um corpo pode não ser necessário. Por exemplo, você não precisará de um corpo para GET (obter) chamadas.
 

Dados retornados

Se a API de resposta enviar de volta um objeto JSON, ele será salvo no Run Log. Assim, você pode fazer referência aos dados retornados nas partes seguintes do fluxo de trabalho.

Agora você conhece os campos que encontrará ao configurar os módulos Call API Profiles e Make API Call. Continue lendo para saber mais sobre como configurar e usar o utilitário.

O que você precisa para começar

• Uma planilha 
  • O ID da planilha
  • Uma coluna que, quando alterada em suas linhas, você queira acionar seu fluxo de trabalho do Bridge
• Bridge
  • Integração do Smartsheet
  • Acionador do fluxo de trabalho do Bridge: Smartsheet - When Column Values are Changed
  • Módulos de fluxo de trabalho do Bridge: Make API Call
• Uma chave de API do Smartsheet. Saiba como gerar uma chave de API para o Smartsheet. 

Começar

Para criar este fluxo de trabalho no Bridge, autentique a integração do Smartsheet para sua área de trabalho do Bridge. Leia as etapas sobre como configurar a integração do Smartsheet para o 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 no processo de criação.

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

Antes de mais nada, extraia todos os módulos necessários para o fluxo de trabalho. 

1. Crie um 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.

Você verá isto no fluxo de trabalho quando terminar: 

Brandfolder Image

Configurar o acionador do fluxo de trabalho

Depois de criar o modelo de fluxo de trabalho básico, comece a configurar o acionador do fluxo de trabalho.

1. Selecione o módulo Trigger.
2. Para abrir o painel de Integration em uma nova guia, na seção Integrations, selecione a Integrations Page.

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

   Você pode usar a opção Connected no logotipo do Bridge para ver uma lista apenas das integrações autenticadas para essa área de trabalho.

4. Expanda a linha de Triggers.
5. Para criar um acionador, selecione o ícone de mais.
6. Preencha os seguintes campos:
   • Trigger Name: crie um rótulo personalizado para o seu acionador.
   • Sheet ID: cole o ID da sua planilha (a planilha que você deseja classificar).
   • Event Type: selecione When Column Values are Changed. 
   • Column Name ou ID: digite o nome da coluna do Smartsheet à qual você deseja responder. Por exemplo, se você quiser classificar linhas na planilha sempre que a prioridade for alterada, digite o nome da sua coluna de prioridade.
   • Select Workflow: selecione na lista suspensa o novo fluxo de trabalho que você acabou de criar.
7. Selecione Save.
8. Nas informações de Trigger, copie o ID da coluna.
   • O ID da coluna estará disponível nas informações do acionador assim que você salvar o acionador do fluxo de trabalho.
9. Cole-a em um bloco de notas ou em qualquer processador de texto. Você precisará do ID da coluna para uma etapa posterior. 

10. Retorne ao seu fluxo de trabalho.
     

    Se você quiser retornar à guia original, atualize a página para ver o acionador.

Acesse os detalhes da chamada de API

Os valores mudam na coluna de prioridade do acionador da planilha neste fluxo de trabalho. Depois que este fluxo de trabalho detecta o(s) acionador(es), ele executa as ações necessárias na mesma planilha. Portanto, para preencher os módulos do Smartsheet, usaremos as referências de dados de tempo de execução (Run Log) do acionador.

Para este fluxo de trabalho, você fará uma chamada de API ao ponto extremidade Smartsheet Sort Sheet. Use a documentação da API do Smartsheet para alterar o exemplo para cURL.

Etapa 2: configurar seu primeiro perfil

Perfis são uma forma de salvar informações importantes para as APIs do sistema às quais você deseja conectar seus fluxos de trabalho. Ao selecionar um perfil no módulo Make API Call, algumas das informações necessárias para fazer a chamada de API já estarão configuradas para você. 

1. Faça login em sua conta do Bridge.
2. Acesse a guia Integrations.
3. Selecione o utilitário Call API.

4. Selecione Add to Profiles.

   Brandfolder Image

   
5. Dê um nome ao seu perfil. Cada nome de perfil deve ser único.
6. Adicione o URL básico da API do sistema à qual deseja se conectar.
   • Neste exemplo, o URL básico para o Smartsheet é https://api.smartsheet.com/2.0/
7. Em Secret Headers, adicione eventuais cabeçalhos que contenham tokens ou informações secretas (por exemplo, tokens de API).
   • Por exemplo, nas chamadas do Smartsheet, você normalmente teria um Header de chave chamado Authorization com o valor definido como Bearer [insira o token de API].
8. Em Headers, adicione eventuais cabeçalhos que devam ser incluídos em todas as chamadas de API que você fizer com o perfil.
   • Neste exemplo, usamos Content-Type como um cabeçalho com um valor definido como application/json.
9. Salve o perfil.

10. Retorne ao seu fluxo de trabalho.

     

Dica do gerador do Bridge

O URL básico é a parte do URL da API do sistema que sempre permanece a mesma, não importa o que você esteja tentando fazer nesse sistema. O ponto de extremidade no módulo Make API Call serve para incluir os detalhes específicos e à medida que você precisa tomar com essa chamada de API.

Exemplo: estamos usando a API do Smartsheet para classificar uma planilha. O URL básico para o perfil de API do Smartsheet é https://api.smartsheet.com/2.0, e a medida específica que estamos tomando com o módulo é classificando uma planilha específica, então colocaremos 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 desejado na lista suspensa.
2. No campo Endpoint, inclua a parte do campo do URL que não foi adicionada ao campo Base URL 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 Method como POST.
   • No campo HTTP Request Body, um corpo ficaria assim: {"sortCriteria": [{"columnId": column_id_here, "direction": "ASCENDING"}]}
   • Form Parameters (se estiver usando; não usamos 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 a sua coluna de prioridade for um menu suspenso, as linhas classificadas estarão em ordem crescente ou decrescente (dependendo de qual você definiu no corpo da chamada de API) dos valores conforme eles são 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 cadeia de caracteres, marque a caixa de seleção Return raw response em Additional settings no módulo.
• Se você precisar incluir cabeçalhos adicionais para uma chamada específica, copie-os na seção HTTP Request Headers.

Opções alternativas para este fluxo de trabalho

Aqui estão algumas ideias sobre como você pode personalizar este fluxo de trabalho:

• Acionar a partir de uma planilha ou coluna diferente daquela que você deseja classificar. Isso exigirá que você altere os detalhes de API Call para se adequar à planilha e à coluna que deseja classificar. 
• Adicionar 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 tomar medidas diferentes com base na alteração feita na coluna Priority (por exemplo, se Priority for 0, mova a linha para fora da planilha e, se Priority for 1, classifique a planilha).
• Usar um acionador de agenda. Ao usar esse acionador, não será necessário responder às alterações, pois ele classificará a planilha uma vez por dia, semana ou mês.

Usar as ferramentas de Call API em todas as 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 usado. Quando os detalhes do perfil precisam ser alterados porque as permissões de um usuário foram alteradas ou quando a API do sistema faz alterações, há um único lugar para fazer esses ajustes e aplicá-los aos fluxos de trabalho que estão usando esse perfil na área de trabalho.
• Para cada API de sistema adicional à qual você precisa se conectar, é possível configurar um novo perfil exclusivo seguindo a primeira parte do guia.