Faça solicitações à API do Discourse com o Zapier

Discourse · Julho 4, 2019, 11:40pm

As solicitações à API do Discourse podem ser automatizadas criando um Zap que usa um Webhook do Zapier como etapa de ação. Este tópico descreverá como realizar solicitações para as seguintes ações:

adicionar usuário a um grupo
conceder uma insígnia personalizada

Para descobrir como realizar outros tipos de solicitações de API com o Zapier, leia este tópico e, em seguida, pesquise na documentação da API do Discourse pela ação que deseja executar. Você também pode descobrir como criar uma solicitação de API para uma ação específica lendo Reverse engineer the Discourse API.

Configurar a etapa de gatilho

Cada Zap deve ter um gatilho e uma etapa de ação. O gatilho é usado para passar dados de um aplicativo para a etapa de ação do Zap. Em alguns casos, o gatilho também pode ser usado para impedir que um Zap conclua sua etapa de ação, a menos que seus dados atendam a certas condições.

Para configurar sua etapa de ação, acesse seu Painel do Zapier e clique no botão Criar um Zap. Um formulário de pesquisa será aberto pedindo que você escolha um aplicativo de gatilho.

Para os exemplos neste tópico, estou usando o evento Novo Usuário do WordPress como a etapa de ação. Isso ocorre porque é fácil configurar para testar as chamadas de API.

O nó “Testar esta etapa” da sua etapa de gatilho permite selecionar uma amostra de dados do seu aplicativo de gatilho que será passada para a etapa de ação do seu Zap. Esses dados serão úteis para configurar a etapa de ação.

Adicionar uma etapa opcional para recuperar detalhes do Discourse

Dependendo dos dados passados pelo seu aplicativo de gatilho, você pode precisar recuperar alguns dados do Discourse antes de fazer sua solicitação de API final. Por exemplo, o gatilho Novo Usuário do WordPress passa o nome de usuário do WordPress e o endereço de e-mail do usuário. Sei que o endereço de e-mail corresponderá ao e-mail do usuário do Discourse, mas para as solicitações de API neste exemplo, preciso saber o nome de usuário do usuário no Discourse.

Para obter os detalhes de um usuário no Discourse a partir do endereço de e-mail, adicione uma etapa de ação ao seu Zap. Selecione “GET” no menu de ação do webhook.

Na etapa de edição do modelo do webhook, insira a URL base do seu site do Discourse, seguida de /admin/users/list/all.json na seção URL. Por exemplo, a URL base do meu site é https://demo.scossar.com, então insiro https://demo.scossar.com/admin/users/list/all.json no campo URL.

Na seção Parâmetros da String de Consulta, insira “email” como a Chave e, em seguida, clique no ícone “Inserir um Campo” para abrir o menu suspenso. Selecione o valor que foi passado pela sua etapa de gatilho e que contém o endereço de e-mail do usuário.

Autenticar a solicitação

Role para baixo no formulário até a seção Cabeçalhos. Esta seção é usada para autenticar a solicitação. Ela requer três pares chave/valor:

Api-Username: o nome de usuário de um usuário administrador no seu site. Na maioria dos casos, o usuário ‘system’ será uma boa escolha para isso.
Api-Key: a Chave de API associada ao nome de usuário que você usou no primeiro par chave/valor
Content-Type: multipart/form-data

A seção Cabeçalhos concluída deve parecer semelhante a esta, mas com a chave de API do seu usuário:

Clique no botão Continuar para ver os dados recuperados do Discourse para esta solicitação.

Adicionar a etapa de ação final

Depois que seu gatilho e a etapa opcional para recuperar dados do Discourse estiverem configurados, clique no link “Adicionar uma etapa” e selecione “Webhooks by Zapier” no menu de ação. Em seguida, será solicitado que você escolha qual método de solicitação deseja usar em sua solicitação de API ao Discourse.

Aqui estão os tipos de solicitação necessários para os exemplos usados neste tópico:

adicionar usuário a um grupo: PUT
conceder insígnia personalizada: POST

Para configurar solicitações de API diferentes dos exemplos deste tópico, consulte a documentação da API do Discourse para ver se há um exemplo da solicitação que você deseja fazer. Se não encontrar um exemplo lá, leia Como fazer engenharia reversa da API do Discourse para aprender a encontrar a URL e o método de solicitação para a ação que deseja executar. Depois de encontrar o método de solicitação, selecione-o no menu de ação.

Observação: se sua solicitação usar o método DELETE, selecione “Solicitação Personalizada” no menu de ação.

Configurar a etapa de ação final

A seção Cabeçalhos da ação pode ser configurada da mesma forma para todas as solicitações de API. Consulte a seção ‘Autenticar a solicitação’ deste tópico para obter detalhes. Se você adicionou a etapa opcional para recuperar detalhes do Discourse, pode configurar a seção Cabeçalhos da ação final exatamente da mesma forma que fez para aquela etapa.

Depois que os pares chave/valor do Cabeçalho forem adicionados, você precisará preencher os campos URL e Dados do formulário para sua solicitação de API.

Adicionar usuário a um grupo

Para adicionar um usuário a um grupo, uma solicitação PUT é feita para /groups/<group_id>/members.json. A maneira mais fácil de encontrar o ID de um grupo é visitar a página do grupo pela interface do usuário do Discourse e, em seguida, inserir .json na URL na barra de endereços do seu navegador. Por exemplo, meu site tem um grupo “suporte” em https://demo.scossar.com/g/support. Ao acessar https://demo.scossar.com/g/support.json, posso ver que o ID do grupo é 41. A URL base do meu fórum é https://demo.scossar.com. A URL na minha etapa de ação final para adicionar usuários a um grupo é definida como https://demo.scossar.com/groups/41/members.json.

A solicitação para adicionar usuários a um grupo requer um parâmetro: uma lista de nomes de usuário separada por vírgulas. Na seção Dados do formulário, insira “usernames” como a chave. Em seguida, clique no ícone “Inserir um Campo” para pesquisar a propriedade de nome de usuário que foi passada do gatilho ou da etapa de ação GET opcional.

No meu caso, quero o nome de usuário recuperado pela etapa GET, então expando o menu “GET” e selecio Username no menu suspenso.

Todas as outras seções do formulário podem permanecer com seus valores padrão.

Clique no botão Continuar e, em seguida, teste sua etapa. Se o usuário que você passou pelas etapas anteriores existir no seu site do Discourse e ele ainda não for membro do grupo que você selecionou, ele deverá ser adicionado ao grupo ao testar a etapa.

Se tudo funcionar conforme o esperado, ative seu Zap.

Conceder uma insígnia personalizada

Para conceder uma insígnia personalizada a um usuário, uma solicitação POST é feita para a URL base do seu fórum + /user_badges. Para o meu site, a URL para conceder insígnias é https://demo.scossar.com/user_badges. O campo URL concluído no Zapier fica assim:

A seção Dados do formulário requer dois pares chave/valor. Adicione uma chave “username” e defina-a como o campo que retorna o nome de usuário do usuário. Adicione uma chave “badge_id” e defina-a como o ID da insígnia que você deseja conceder. Você pode encontrar o ID da insígnia acessando sua página Admin / Insígnias e selecionando a insígnia no menu lateral esquerdo. Você verá o ID da insígnia como o último valor da URL na barra de endereços do seu navegador.

A insígnia que estou concedendo tem um ID de 105, então minha seção Dados concluída fica assim:

Certifique-se de ter configurado a seção Cabeçalhos do formulário e, em seguida, clique em Continuar. Em seguida, clique no botão Enviar teste para testar seu Zap. O usuário que você passou pelas etapas anteriores deverá receber a insígnia.

Se tudo estiver funcionando corretamente, ative o Zap.

aj_silvers · Julho 7, 2019, 5:44pm

Esse fluxo de trabalho pode ser usado para criar automaticamente uma conta para um novo usuário e adicioná-lo a um grupo específico do Discourse?

O caso de uso aqui é o seguinte: alguém compra um produto de treinamento e eu quero adicionar automaticamente essa pessoa ao subfórum relevante do Discourse para aquele produto.

Consigo levar os dados do novo cliente para o Zapier, mas o Zap padrão do Discourse não tem capacidade de criar contas — estou apenas querendo saber se consigo fazer isso via API e link de webhook, como você descreve neste exemplo.

Obrigado!

simon · Julho 7, 2019, 5:56pm

A abordagem mais simples seria enviar um e-mail de convite à pessoa após a compra. Você pode configurar o convite para que o usuário seja adicionado automaticamente a um grupo do Discourse ao aceitar o convite. Consulte Automate sending Discourse invite emails with Zapier para detalhes.

Se o envio de convites não for uma opção para você, será possível usar um webhook do Zapier para criar um usuário no Discourse. A página Discourse API Docs fornece detalhes sobre a solicitação para criar um usuário.

aj_silvers · Julho 7, 2019, 7:13pm

Obrigado, @simon! Vou tentar o convite por e-mail. Sem dúvida, algumas pessoas não receberão, não encontrarão ou não abrirão, mas é definitivamente a opção mais fácil.

Agradeço também a resposta rápida!

pfaffman · Julho 7, 2019, 7:27pm

Geralmente, é mais fácil que quem vende o produto faça as chamadas à API do Discourse diretamente.

Nacho_Caballero · Dezembro 2, 2019, 6:53pm

Existe algum motivo pelo qual isso funciona para mim quando faço no Zapier, mas recebo uma resposta vazia ao tentar fazer minha própria solicitação fetch?

Estou usando ObservableHQ, mas a ideia é a mesma. Isso não deveria funcionar?:

fetch("https://mycommunity.com/g.json", {
  headers: {
    "Content-Type": "multipart/form-data",
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
  method: "GET",
  mode: "no-cors"
})

simon · Dezembro 2, 2019, 7:02pm

Consegue fazer com que solicitações de API para o Discourse funcionem usando chamadas nesse formato no ObservableHQ? Parece que deve haver algo errado com o formato da solicitação.

Você também pode verificar as solicitações fazendo chamadas curl no seu terminal ou usando o Postman.

Nacho_Caballero · Dezembro 2, 2019, 11:12pm

Ok, descobri o que precisava fazer:

Instalar cors-anywhere localmente e executar o servidor
Modificar a solicitação para incluir o proxy reverso antes do ponto de extremidade da API e chamar o método json no objeto Resposta Fetch:

await (fetch("http://localhost:8080/mycommunity.com/g.json", {
  headers: {
    "Api-Username": Secret("DISCOURSE_USERNAME"),
    "Api-Key": Secret("DISCOURSE_KEY")
  },
})).json()

markersocial · Dezembro 4, 2020, 11:20am

Vou deixar isso aqui, pode valer a pena conferir:

Bernstein · Janeiro 5, 2021, 11:05pm

Olá @simon, obrigado por este tutorial. Estou configurando isso no Zapier, mas meu fórum não possui essa URL para conceder insígnias.

Gostaria de saber: essa não é uma URL padrão para todas as instalações do Discourse, ou a URL pode ter mudado em uma atualização recente?

simon · Janeiro 6, 2021, 1:08am

Deveria ter. Não é uma URL que pode ser acessada através da interface do usuário do Discourse. Acabei de verificar a rota no meu site seguindo as etapas descritas aqui: Como fazer engenharia reversa da API do Discourse. Com base nisso, parece que os detalhes fornecidos no tópico ainda estão atualizados.

Bernstein · Janeiro 6, 2021, 1:35am

Não foi surpresa alguma, foi o meu próprio erro.

Tópico		Respostas	Visualizações
Automate sending Discourse invite emails with Zapier Integrations how-to , tasks	37	9276	3 de Maio de 2024
Automatically add users to groups via Zapier Feature	16	2627	7 de Abril de 2022
Grant a custom badge through the API Integrations how-to , rest-api	9	7673	18 de Novembro de 2023
Use the Zapier Discourse Zap Templates Integrations how-to	8	5122	8 de Julho de 2022
Integrations Index Integrations index	1	948	25 de Maio de 2024