Neste tutorial, você aprenderá a usar o Cloud Run functions para implementar um comando de barra do Slack que pesquisa a API Knowledge Graph do Google.
Objetivos
- Criar um Slash Command no Slack.
- Escrever e implantar um Cloud Run functions HTTP.
- Pesquisar a API Google Knowledge Graph usando o Slash Command.
Custos
Neste documento, você vai usar os seguintes componentes faturáveis do Google Cloud:
- Cloud Run functions
Para gerar uma estimativa de custo baseada na projeção de uso deste tutorial, use a calculadora de preços.
Antes de começar
- Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.
-
Para inicializar a gcloud CLI, execute o seguinte comando:
gcloud init
-
In the Google Cloud console, on the project selector page, select or create a Google Cloud project.
Roles required to select or create a project
- Select a project: Selecting a project doesn't require a specific IAM role—you can select any project that you've been granted a role on.
-
Create a project: To create a project, you need the Project Creator
(
roles/resourcemanager.projectCreator
), which contains theresourcemanager.projects.create
permission. Learn how to grant roles.
-
Verify that billing is enabled for your Google Cloud project.
-
Enable the Cloud Functions, Cloud Build, and Google Knowledge Graph Search APIs.
Roles required to enable APIs
To enable APIs, you need the Service Usage Admin IAM role (
roles/serviceusage.serviceUsageAdmin
), which contains theserviceusage.services.enable
permission. Learn how to grant roles. -
Install the Google Cloud CLI.
-
Ao usar um provedor de identidade (IdP) externo, primeiro faça login na gcloud CLI com sua identidade federada.
-
Para inicializar a gcloud CLI, execute o seguinte comando:
gcloud init
- Prepare seu ambiente de desenvolvimento.
- O usuário executa o Slash Command
/kg <search_query>
em um canal Slack. - O Slack envia o payload do comando ao endpoint do gatilho da função.
- A função a seguir envia uma solicitação com a consulta de pesquisa do usuário para a API Knowledge Graph:
- A API Knowledge Graph responde com todos os resultados encontrados.
- A função formata a resposta em uma mensagem do Slack.
- A função envia a mensagem de volta ao Slack.
- O usuário vê a resposta formatada no canal do Slack.
Clone o repositório do app de amostra na máquina local:
Node.js
git clone https://github.com/GoogleCloudPlatform/nodejs-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Python
git clone https://github.com/GoogleCloudPlatform/python-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Go
git clone https://github.com/GoogleCloudPlatform/golang-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Java
git clone https://github.com/GoogleCloudPlatform/java-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Ruby
git clone https://github.com/GoogleCloudPlatform/ruby-docs-samples.git
Outra alternativa é fazer o download da amostra como um arquivo ZIP e extraí-lo.
Mude para o diretório que contém o código de amostra das funções do Cloud Run:
Node.js
cd nodejs-docs-samples/functions/slack/
Python
cd python-docs-samples/functions/slack/
Go
cd golang-samples/functions/slack/
Java
cd java-docs-samples/functions/slack/
Ruby
cd ruby-docs-samples/functions/slack/
Crie um aplicativo Slack para hospedar o Slack Slash Command. Associe-o a uma equipe do Slack onde você tem permissões para instalar integrações.
Vá para os comandos do Slash e clique no botão Criar novo comando.
Insira
/kg
como o nome do comando.Digite o URL do comando:
Node.js
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kgSearch
Python
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search
Go
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/KGSearch
Java
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/java-slack-function
Ruby
https://YOUR_REGION-YOUR_PROJECT_ID.cloudfunctions.net/kg_search
em que
YOUR_REGION
é a região em que a função está implantado eYOUR_PROJECT_ID
é seu ID do projeto do Cloud.Ambos os valores são visíveis em seu terminal quando sua função termina de ser implantada.
Clique em Salvar.
Vá para Informações básicas.
Clique em Instalar aplicativo no espaço de trabalho e siga as instruções na tela para ativar o aplicativo do seu espaço de trabalho.
Seu Slack Slash Command ficará on-line em breve.
Digite o comando no canal do Slack:
/kg giraffe
Verifique os registros para confirmar se as execuções foram concluídas:
gcloud functions logs read --limit 100
- In the Google Cloud console, go to the Manage resources page.
- In the project list, select the project that you want to delete, and then click Delete.
- In the dialog, type the project ID, and then click Shut down to delete the project.
Se a gcloud CLI já estiver instalada, atualize-a executando o seguinte comando:
gcloud components update
Como visualizar o fluxo de dados
O fluxo de dados no aplicativo de tutorial do Slack Slash Command envolve vários passos:
Isto pode ajudar a visualizar os passos:
Como criar a chave da API Google Knowledge Graph
Na página Credenciais do consoleGoogle Cloud , clique no botão Criar credenciais e selecione Chave de API. Lembre-se dessa chave, já que ela será usada para acessar a API Knowledge Graph na próxima seção.
Como preparar a função
Como implantar a função
Para implantar a função executada quando você (ou o Slack) faz uma solicitação HTTP POST para o endpoint da função, execute o comando a seguir no diretório que contém o código da amostra (ou o arquivo pom.xml
para Java):
Substitua YOUR_SLACK_SIGNING_SECRET
pelo secret de assinatura fornecido pelo Slack na página Informações básicas da configuração do aplicativo e YOUR_KG_API_KEY
pela chave da API Knowledge Graph criada anteriormente.
Node.js
gcloud functions deploy kgSearch \ --runtime nodejs20 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Node.js compatível a fim de executar a função.
Python
gcloud functions deploy kg_search \ --runtime python312 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Python a fim de executar a função.
Go
gcloud functions deploy KGSearch \ --runtime go121 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão do Go compatível a fim de executar a função.
Java
gcloud functions deploy java-slack-function \ --entry-point functions.SlackSlashCommand \ --runtime java17 \ --memory 512MB \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Java a fim de executar a função.
Ruby
gcloud functions deploy kg_search --runtime ruby33 \
--trigger-http \
--set-env-vars "SLACK_SECRET=YOUR_SLACK_SIGNING_SECRET
,KG_API_KEY=YOUR_KG_API_KEY
" \
--allow-unauthenticated
Use a flag --runtime
para especificar o ID do ambiente de execução de uma versão compatível do Ruby a fim de executar a função.
Configurar o aplicativo
Depois que a função é implementada, você precisa criar um Comando de barra do Slack que envia a consulta para a função toda vez que o comando for acionado:
Como entender o código
Como importar dependências
O aplicativo importa várias dependências para se comunicar com os serviços do Google Cloud Platform:
Node.js
Python
Go
Java
Ruby
Como receber o webhook
A função a seguir é executada quando você ou o Slack fazem uma solicitação HTTP POST para o ponto de extremidade da função.
Node.js
Python
Go
Java
Ruby
A função a seguir autentica a solicitação recebida verificando o
cabeçalho X-Slack-Signature
fornecido pelo Slack:
Node.js
Python
Go
Java
Ruby
Como consultar a API Knowledge Graph
A função a seguir envia uma solicitação com a consulta de pesquisa do usuário para a API Knowledge Graph:
Node.js
Python
Go
Java
Ruby
Como formatar a mensagem do Slack
Por fim, a seguinte função exibe para o usuário o resultado do Knowledge Graph em uma mensagem do Slack ricamente formatada:
Node.js
Python
Go
Java
Ruby
Tempos limite da API Slack
A API do Slack espera que sua função responda dentro de 3 segundos após receber uma solicitação de webhook.
Os comandos deste tutorial, no geral, levam menos de 3 segundos para responder. Para
comando de execução mais longa, recomendamos configurar uma função para pedidos push
(incluindo seu response_url
)
para um tópico do Pub/Sub que atua como uma fila de tarefas.
Em seguida, crie uma segunda função acionada por Pub/Sub
que processa essas tarefas e envia os resultados de volta para o response_url
do Slack.
Como usar o comando Slash
Limpar
Para evitar cobranças na sua conta do Google Cloud pelos recursos usados no tutorial, exclua o projeto que os contém ou mantenha o projeto e exclua os recursos individuais.
Excluir o projeto
O jeito mais fácil de evitar cobranças é excluindo o projeto que você criou para o tutorial.
Para excluir o projeto:
Como excluir a função
Para excluir o Cloud Function implantado neste tutorial, execute o seguinte comando:
Node.js
gcloud functions delete kgSearch
Python
gcloud functions delete kg_search
Go
gcloud functions delete KGSearch
Java
gcloud functions delete java-slack-function
Ruby
gcloud functions delete kg_search
Também é possível excluir funções do Cloud Run pelo consoleGoogle Cloud .