Tutorial do Okta Workflows: Crie um conector para a API do Spotify (com OAuth 2.0)

Este tutorial ensinará como construir um conector para a API do Spotify que usa OAuth para autenticação usando o Okta Workflows Connector Builder.

• Conector para a API do Spotify
• Crie um conector para a API do Spotify
• Recursos

Conector para a API do Spotify

Você criará um conector para a API do Spotify porque ela usa OAuth para autenticação. Este tutorial ensinará você a criar um conector no Construtor de Conectores que usa OAuth para autenticação.

A autenticação OAuth é um tópico avançado. Se você é novo no Connector Builder, leia e conclua outros artigos e tutoriais desta série: 

• Entendendo os Conectores do Okta Workflows.
• Okta Workflows Tutorial: Build a Connector for OpenWeather API.

Se você deseja chamar a API do Spotify usando o card API Connector, leia este artigo da KB:

• Como chamar a API do Spotify do Okta Workflows (Exemplo de Autenticação OAuth).

Esta KB ensinará você a configurar a conexão OAuth e chamar a API do Spotify usando o cartão API Connector.

Crie um conector para a API do Spotify

Nesta seção, você criará um conector para o Spotify no Connector Builder.

O Connector Builder usa fluxos de Workflows e cards (ação, função) para construir um conector.

Um conector consiste em vários fluxos:

• Um flow para fazer requisições HTTP.
• Um fluxo para verificar se a autenticação no serviço está funcionando.
• Um ou mais fluxos de ação. Cada fluxo de ação chama o endpoint da API de um serviço.
• Fluxo de ação personalizada para permitir chamar qualquer endpoint de API no serviço (veja o tutorial Build a Connector for OpenWeather API).

Primeiro, você precisa de uma conta do Spotify antes de começar a construir o conector.

Configure uma conta e um aplicativo Spotify

Crie uma conta do Spotify

1. Crie uma conta no Spotify, se você não tiver uma.

Criar um aplicativo

Após implementar um fluxo de autorização, o aplicativo fornecerá um token de acesso para fazer chamadas à API do Spotify.

1. Para criar um aplicativo, vá para seu Painel, clique em Criar um aplicativo.
2. Insira Workflows Connector Builder para Nome do aplicativo.
3. Insira Workflows Connector Builder app para App description.
4. Insira http://localhost:8080 para os URIs de Redirecionamento (Redirect URIs). Você mudará esse valor mais tarde.
5. Verifique a Web API para Quais APIs/SDKs você está planejando usar?
6. Marque a caixa de seleção Termos de Serviço do Desenvolvedor.
7. Clique em Save para criar o aplicativo.

Aplicativo Spotify.

Criar um projeto de conector

 

Iniciar o Connector Builder

1. Clique no menu ao lado do seu nome para iniciar o Connector Builder.

Inicie o Connector Builder.

Criar um projeto de conector

1. Clique no ➕ no painel esquerdo para criar um projeto de conector.
2. Insira Spotify para o Nome do conector.
3. Insira Spotify connector para a Connector description.
4. Clique em Save para criar o projeto.

Projeto do conector Spotify.

Fluxos de conector e autenticação

Fluxos de conector

O conector que você criará tem três fluxos:

• httpHelper: gerencia todas as solicitações de autenticação e HTTP para o conector.
• authPing: verifica a integridade da conexão.
• List User Albums: lista os álbuns atuais do Spotify dos usuários (documentos da API).

Autenticação

A autenticação é onde você define os parâmetros necessários para criar uma conexão segura com o serviço de API.

Quando um usuário final cria uma conexão com seu serviço, a caixa de diálogo New Connection coleta os detalhes de autenticação específicos.

Existem três tipos de autenticação:

• Basic: usa nome de usuário e senha.
• OAuth 2.0: concede acesso limitado a recursos a terceiros. Você pode usar os tipos de concessão Authorization Code ou Client Credential em um conector.
• Customizado: usa chave de API ou outro processo de autenticação.

Você configurará uma conexão OAuth para o Spotify.

Criar autenticação para a API do Spotify

Criar uma conexão OAuth

1. Role para baixo e clique em Set up authentication na página Overview para criar uma conexão.
2. Selecione Oauth 2.0 na lista Auth Type.
3. Selecione Código de Autorização na Grant Type.
4. Insira https://accounts.spotify.com para o URL Base.
5. Insira /authorize para o Authorize Path.
6. Insira /api/token para o Caminho do Token.
7. Deixe o campo Refresh Token Path em branco.

Criando uma conexão.

Atualize o URI de redirecionamento no aplicativo Spotify

1. Copie o link em Redirect URI. Este é o URL de callback.
2. Retorne ao aplicativo Spotify que você criou anteriormente. Clique em Settings.
3. Na parte inferior da página, clique em Edit.
4. Na seção Redirect URIs, clique em Remove para excluir o URI atual.
5. Cole o URI do Connector Builder e clique em Add.
6. Clique em Save para salvar as alterações.

Configure o Client ID e o Client Secret

1. Retorne ao Connector Builder.
2. Mantenha Developer para a Propriedade do Cliente.
3. Copie o Client ID do aplicativo Spotify e cole-o no campo Client ID na conexão.
4. Copie o Client Secret do aplicativo Spotify (clique em View client secret) e cole-o no campo Client Secret na conexão.

Definir escopo

A API Get Current User’s Playlists requer o escopo playlist-read-private. Escopos definem os recursos aos quais o aplicativo tem acesso. 

Criando uma nova conexão (continuação).

1. Na seção Scopes, clique em Add Scope.
2. Insira playlist-read-private para o Nome.
3. O lado direito mostra a visualização da conexão. Clique em Salvar para criar a conexão.

Informações de conexão do Spotify.

Crie um fluxo para fazer solicitações HTTP

Você criará um flow chamado httpHelper.

O httpHelper é um fluxo de sistema que gerencia a autenticação e as solicitações HTTP para o conector. O fluxo httpHelper é um fluxo auxiliar; outros fluxos podem chamá-lo. O fluxo tem:

• Várias entradas.
• Cartões de função para construir consulta de solicitação, cabeçalho e informações do corpo.
• O card HTTP – Raw Request para fazer uma chamada para uma API.
• Várias saídas.

Criar um fluxo

1. Abra a página Flows.
2. Para criar um fluxo, clique em + Novo Fluxo.
3. Clique em Unnamed no canto superior esquerdo para nomear o fluxo.
4. Insira httpHelper para o Nome do fluxo.
5. Insira Este fluxo gerencia todas as solicitações de autenticação e HTTP para o conector para a Description.
6. Marque a opção Save all data that passes through the Flow? option.
7. Para salvar o fluxo, clique em Save.

Configurar entradas de fluxo

1. Clique em Adicionar evento e escolha Helper Flow.
2. Adicione os seguintes campos no cartão Helper Flow:
   • relative_url (tipo: Texto).
   • request_method (Text).
   • query (Object).
   • headers (Objeto).
   • body (Objeto).

O fluxo httpHelper com entradas

fluxo httpHelper.

Configure o URL da API

O conector pode suportar múltiplos endpoints do Spotify. O URL base permanece o mesmo, e o URL relativo mudará. Você precisa combinar os dois valores em um URL completo.

1. Adicione o card Text – Concatenate após o card Helper Flow.
2. Insira https://api.spotify.com o campo text 1.
3. Conecte relative_url ao campo text 2.
4. Renomeie o campo de saída do card.
   • Para editar o cartão, clique em ⚙️ > Editar cartão (Edit card).
   • Para renomear o campo de saída, clique em seu ícone ✏️ e defina o nome como full_url.

Configurando a URL.

Configure os cabeçalhos

Você precisa configurar dois parâmetros de cabeçalho:

• Content-Type: application/json.
• Authorization: Bearer access_token.

A conexão que você configurou irá adquirir o token de acesso. O campo Conexão lista o valor do Token de Acesso no primeiro card.

Para configurar o cabeçalho de Authorization:

1. Adicione o card Text – Compose.
2. Digite Bearer dentro do card.
3. Conecte o Access Token após a string Bearer (adicione um espaço entre as strings).
4. Renomeie o campo output do card Compose para bearer.

Para configurar o cabeçalho Content-Type:

1. Adicione o cartão Objeto – Construir.
2. Crie um campo Content-Type e, para o valor, insira application/json.
3. Crie um campo Authorization e, para o valor, conecte o campo bearer do card Compose.
4. Renomeie o campo de saída para headers_auth.

Voc\[ê precisa mesclar os cabe\[ç\[alhos Content-Type e Authorization com quaisquer cabe\[ç\[alhos que um usu\[á\[rio do Workflows possa fornecer.

1. Adicione o cartão Object – Merge.
2. Conecte o campo headers do primeiro card ao campo object 1.
3. Conecte headers_auth do cartão Construct ao campo object 2.
4. Renomeie o campo output para merged_headers.

httpHelper flow with headers cards.

Faça a chamada de API

1. Adicione o card HTTP – Raw Request.
2. Crie as seguintes conexões:
   • full_url para o campo url no cartão Raw Request.
   • request_method para o method no cartão Raw Request.
   • merged_headers para o campo headers no cartão Raw Request.
   • query do primeiro cartão ao campo query.
   • body para o campo body.

Configurar saídas de flow

1. Conecte os campos statusCode, headers e body do card HTTP – Raw Request ao card Flow Control – Return.
2. Altere o tipo de campo body para Object.

Fluxo final de httpHelper:

fluxo httpHelper.

Teste o fluxo

1. Clique em Run para testar o fluxo.
2. Selecione New connection na lista Test Connection.
3. Insira Spotify para o campo Name.
4. Insira Conexão do Spotify para o campo Description.
5. Clique em Create. Você verá um pop-up pedindo para você entrar no Spotify e permitir que o aplicativo que você criou (Workflows Connector Builder) acesse suas informações de playlist.
6. Insira /v1/me/playlists para o campo relative_url.
7. Insira GET para o campo request_method.
8. Clique em Run para testar o fluxo.

Criar um fluxo para verificar uma conexão válida

Você criará um fluxo chamado _authPing. Um fluxo _authPing é um fluxo de sistema usado pela plataforma para chamar uma API e verificar se há autorização válida.

Esta ação funciona como uma verificação de validação e é executada quando você autentica o conector pela primeira vez, adiciona novos conectores ou abre fluxos.

Criar um fluxo

1. Retorne à visualização do projeto do conector.
2. Clique em + Novo Fluxo na página Fluxos.
3. Clique em Add event e selecione o evento Authping.
4. Para salvar o fluxo, clique em Unnamed no canto superior esquerdo.
5. Insira _authping para o Name.
6. Insira Connection health check para a descrição.
7. Marque a opção Save all data that passes through the Flow? option.
8. Clique em [Salvar].

Fluxo _authping.

Adicione cards de verificação de integridade da conexão

1. Clique em Add function e selecione o card Error Handling – If Error.
2. No bloco Try (selecionado automaticamente), clique em ➕, depois em function (ícone de calculadora) e selecione o card Flow Control – Call Flow.
3. No card Chamar Fluxo, clique em Escolher Fluxo.
4. Selecione o fluxo httpHelper e clique em Choose.

O fluxo se parece com isto:

Fluxo _authping com o card Call Flow.

Este fluxo chama o fluxo httpHelper para verificar se a conexão com o serviço está funcionando. Você deve usar um endpoint de API que exija autenticação.

Observação: A equipe do Okta Workflows recomenda uma solicitação com o menor tamanho de resposta. Por exemplo, algumas APIs têm um endpoint /me para obter informações sobre o usuário logado.

A API do Spotify tem um endpoint /me que voc\[ê pode usar neste fluxo.

Conclua a configuração do cartão Call Flow:

1. Insira /v1/me para o relative_url.
2. Insira GET para o request_method.
3. Deixe os campos query, headers e body em branco.
4. Conecte o campo Connection do primeiro cartão ao campo Connection no cartão Call Flow.

Chamando o endpoint /me.

Para criar saídas no card Call Flow:

1. Clique dentro da área Click or drag to create e crie os seguintes campos de saída:
   • statusCode (tipo Número).
   • headers (Objeto).
   • body (Objeto).

Cartão de Fluxo de Chamada com saídas.

Em seguida, você configurará uma mensagem quando a conexão estiver funcionando e uma mensagem quando a conexão não estiver funcionando.

Para configurar uma mensagem quando para conexão de trabalho:

1. Clique no ➕ após o card Call Flow dentro do card If Error e selecione o card Flow Control – Assign.
2. Adicione um campo message e defina-o para o valor The connection is successful no card Control – Assign .

Crie saídas para o cartão If Error:

1. Clique em View Outputs no cartão If Error (canto superior direito). O cartão abre uma seção onde você define as saídas do cartão.
2. Clique dentro da caixa de campo e crie duas saídas:
   • statusCode.
   • mensagem.
3. Crie as seguintes conexões:
   • statusCode do card Call Flow para o primeiro subcampo de statusCode.
   • message do card Assign para o primeiro subcampo de message.

Os cartões se parecem com isto:

Configure uma mensagem quando a conexão estiver funcionando.

Para configurar uma mensagem quando a conexão não estiver funcionando:

1. Usando a lista onde diz Try, mude para o bloco If Error no cartão If Error.
2. Adicione dois campos ao objeto Error:
   • statusCode (tipo Text).
   • description (Texto).
3. Clique em ➕ à direita do objeto Error dentro do bloco If Error e adicione o card Text – Concatenate.
4. Crie as seguintes conexões:
   • description do objeto Error para o campo text 1.
   • Insira : (dois pontos) no campo texto 2.
   • Clique para criar um terceiro campo e conecte message de Error a ele.

Em seguida, você conectará a mensagem à saída do card If Error.

1. Clique em View Outputs no card If Error.
2. Crie as seguintes conexões:
   • statusCode de Error para o segundo subcampo de statusCode.
   • saída de Concatenate para o segundo subcampo da mensagem.

Os cartões se parecem com isto:

Configure uma mensagem quando a conexão não estiver funcionando.

Configurar a saída do fluxo

O card Flow Control – Return Status tem dois campos: working e serviceResponse. Você usará as informações disponíveis neste fluxo para definir esses campos.

1. Clique em ➕ após o cartão If Error e adicione o cartão True/False – Compare.
2. Conecte statusCode da saída do card Se Erro para o campo valor a.
3. Insira 200 para o campo value b.
4. Renomeie o campo de saída result para working.

Configurando o código de status da conexão.

Se a chamada para a API for bem-sucedida (200), a conexão está funcionando.

1. Clique em ➕ após o cartão Verdadeiro/Falso – Comparar e adicione o cartão Objeto – Construir.
2. Crie dois campos no cartão Construct:
   • statusCode (tipo Text).
   • body (Texto).
3. Crie as seguintes conexões:
   • statusCode da saída do cartão If Error para o campo statusCode no cartão Construct.
   • mensagem da saída do cartão Se Erro para o campo corpo no cartão Construir.
4. Renomeie o campo output no cartão Construct para serviceResponse.

Configurando a resposta de status da conexão.

Para configurar as saídas de fluxo:

1. Conecte o working do card Compare ao campo working no card Return Status.
2. Conecte o serviceResponse do cartão Construct ao campo serviceResponse no cartão Return Status.

O fluxo completo:

O fluxo completo _auththing.

Teste o fluxo

1. Salve o flow.
2. Clique em Run.
3. Selecione a conexão Spotify e clique em Run.

Criar uma ação para listar os álbuns do usuário

Nesta seção, você criará uma ação de conector para o endpoint Get Current User’s Playlists.

Criar um fluxo

1. Volte para a visualização do projeto do conector.
2. Clique em + New Flow para criar um novo fluxo.
3. Clique em Unnamed no canto superior esquerdo para nomear o fluxo.
4. Insira List Current User Albums para o Flow name.
5. Insira List current user Spotify albums para a Description.
6. Marque a opção Save all data that passes through the Flow? opção
7. Clique em Save para salvar o fluxo.

Configurar o fluxo como uma ação

Um fluxo de ação faz uma chamada à API de serviço.

Para configurar este fluxo como um fluxo de ação:

1. Clique em Add event e, em seguida, no tipo de evento Action.

O fluxo de ação não precisa de entradas, pois o endpoint Get Current User’s Playlists não tem entradas.

O fluxo se parece com isto:

List Current User Albums action.

Chamar a API do Spotify

Nesta etapa, você fará uma chamada para a API do Spotify.

1. Adicione o cartão Controle de Fluxo – Chamar Fluxo.
2. Clique em Choose Flow, selecione o fluxo httpHelper e clique em Choose.
3. Insira /v1/me/playlists para o campo relative_url.
4. Insira GET para o request_method.
5. Conecte o campo Connection do primeiro cartão ao campo Connection no cartão Call Flow.
6. Crie três saídas para o cartão Call Flow:
   • statusCode (tipo Número).
   • headers (Objeto).
   • body (Objeto).

Cartão Call Flow.

Criar saídas de fluxo

Crie as seguintes saídas no card Flow Control – Return Outputs:

1. Clique em Add Outputs.
2. Abra Add group e selecione Add Static Group.
3. Crie três saídas:
   • Código de Status (digite Número).
   • Headers (Object).
     • Exclua a entrada de chave vazia.
   • Body (Object).
     • Exclua a entrada de chave vazia.
4. Clique em Apply para salvar as saídas.
5. Conecte os dados do cartão Call Flow ao cartão Return Outputs:
   • statusCode para o campo Status Code.
   • headers para o campo Headers.
   • body para o campo Body.

O final do fluxo se parece com isto:

O fluxo de ação completo List Current User Albums.

Teste o fluxo

1. Clique em Run para testar o fluxo.
2. Selecione a conexão Spotify da lista Test Connection e clique em Run.

Implementar o conector

Ativar fluxos

Os fluxos precisam estar ativados antes de serem implementados.

1. Retorne à página Fluxos.
2. Ligue os três fluxos.

Atualizar as configurações do conector

Nesta seção, você deverá inserir informações adicionais nas configurações.

1. Retorne à visualização principal do projeto.
2. Abra a página Overview.
3. Clique em Edit na seção Settings.
4. Baixe e defina o ícone do Spotify para o conector.
5. Altere a Cor de Destaque se desejar.
6. Insira as informações de User Documentation URL e Support Contact Email.
7. Clique em Save para salvar todas as alterações.

Configurações do conector.

Implementar o conector

Para implantar o conector:

1. Mude para a guia Deployment.
2. Clique em Create test version.
3. Selecione as três reticências verticais em Actions para uma versão de teste que você criou e selecione Deploy Version.

Você verá o conector implantado na seção Private deployment.

Implantação do conector.

Você está pronto para usar o conector em um fluxo.

Usando o conector em um fluxo

Nesta etapa, você usará a ação do conector em um fluxo.

Conector do Spotify.

Adicionar o card

Ação do conector do Spotify.

1. Crie um novo fluxo no Workflows.
2. Clique em Add app action e selecione o conector Spotify. Você também pode pesquisá-lo.
3. Selecione a ação Spotify – List Current User Albums.

Crie uma conexão

1. Clique em + New Connection e siga as etapas para criar uma conexão para o Spotify.

Ação Spotify – Listar álbuns do usuário atual.

Teste

1. Teste o cartão ou o fluxo.

Testando o fluxo.

Parabéns

Bom trabalho!

Você construiu um conector para o Spotify que alavanca o OAuth para autenticação. 

Recursos

📚 Criando um Conector Personalizado no Okta Workflows, uma Série de Vídeos.

📖 Documentação do Okta Workflows Connector Builder.

🍫 Obtenha ajuda de especialistas em Workflows durante o horário de atendimento da comunidade semanal.

📺 Aprenda com os vídeos do Workflows.

🛟 Obtenha ajuda do suporte: discuta um tópico do Workflows ou faça uma pergunta.

🙋🏻‍♀️ Obtenha ajuda da comunidade: junte-se ao canal #okta-workflows no MacAdmins Slack.