Como usar a API do SurveyMonkey

A SurveyMonkey é uma das ferramentas de design e distribuição de pesquisas mais populares no mercado. Tem alguns recursos robustos e uma interface intuitiva. Mas pode ser entediante criar manualmente vários coletores para uma pesquisa. Muitas das etapas são repetitivas e, atualmente, não há funcionalidade clone.

Podemos aproveitar as APIs da SurveyMonkey para automatizar o processo de criação de coletores e muito mais.

Nesta demonstração, escreverei uma função simples do Script do Google App que cria um coletor para uma pesquisa do SurveyMonkey automaticamente.

Primeiro, você precisa criar um projeto de script do aplicativo do Google . Vá para o Google Drive -> Novo -> Mais -> Google App Script.

Para fazer uma solicitação à SurveyMonkey por meio do nosso script, precisamos usar um serviço de script de aplicativo do Google chamado Serviço de busca de URL .

Vamos criar uma solicitação POST para o SurveyMonkey para criar um coletor para uma pesquisa, de acordo com a API do Survey Monkey .

Antes de entrarmos nos detalhes de como criar a solicitação, precisamos autorizar nosso script a fazer alterações em nome da nossa conta da SurveyMonkey. Para fazer isso, crie um aplicativo no SurveyMonkey. Isso nos dará um token de acesso para repassar nossa solicitação.

Existem dois tipos de aplicativos no SurveyMonkey – públicos e privados. Para nosso propósito, um aplicativo privado é suficiente. Mas observe, está sujeito ao limite de chamadas da API: 120 chamadas / minuto e 500 chamadas / dia. Chamadas adicionais estão disponíveis para compra. Se você precisar criar um conector mais genérico para diferentes contas da SurveyMonkey, precisará de um aplicativo público. O aplicativo público não tem limites de chamadas, mas precisa atender aos critérios da SurveyMonkey.

Como obter o token de acesso

  1. Faça login na sua conta da SurveyMonkey em https://developer.surveymonkey.com/ e crie um aplicativo privado.

Criar um aplicativo particular no SurveyMonkey

2. Vá para Configurações -> Atualizar Escopos -> Implantar o Aplicativo

Atualizar Escopos necessários para o aplicativo. Implante o Aplicativo pressionando o botão 'Implantar'.

3. Obtenha o token de acesso na seção Credenciais na guia Configurações

Token de Acesso é o na guia de configurações

Na nota lateral, se você alterar os escopos do seu aplicativo no futuro, ele gerará um novo token de acesso.

Para o propósito deste projeto, só precisaremos acessar nossa própria conta do SurveyMonkey, portanto, esse token de acesso é suficiente.

Se seu aplicativo acessar muitas contas da SurveyMonkey, implemente o fluxo de três etapas do OAuth 2.0 . Esse fluxo gera um token de acesso de longa duração que seu aplicativo pode usar com todas as chamadas de API para a conta associada da SurveyMonkey. É importante observar que o token de acesso concede somente acesso quando usado em combinação com suas credenciais da API (ID do cliente) e somente para a conta da SurveyMonkey que foi autorizada. Seu aplicativo precisará obter tokens de acesso adicionais para cada conta da SurveyMonkey que você deseja acessar.

Autorize nosso script com o token de acesso

Agora temos nosso token de acesso! Precisamos transmitir o token de acesso quando tentarmos acessar a SurveyMonkey por meio do nosso script. Para fazer isso, precisamos passar as informações de cabeçalho para cada solicitação feita no seguinte formato:

'headers': {'Authorization': 'bearer your_access_token'}

Antes de fazermos um colecionador, precisamos de mais uma informação – o ID da pesquisa para a qual criaremos um coletor. Pelo que sei, esse ID não está acessível na interface do SurveyMonkey. Mas podemos encontrá-lo através da API .

Encontre o ID da pesquisa por meio da API

Escreva a seguinte função no seu arquivo de script do Google App.

function getSurveyID () {

var options = {
'método': 'GET',
'headers': {'Authorization': 'bearer your_access_token'},
'contentType': 'aplicativo / json'
};
var result = UrlFetchApp.fetch (' https://api.surveymonkey.com/v3/surveys?title=Your%20Survey' , opções);
if (result.getResponseCode () == 200) {

var params = JSON.parse (result.getContentText ());

Logger.log (params.data [0] .id);

}
}

Substitua your_access_token pelo seu token de acesso, Your% 20Survey pelo título da sua pesquisa.

Em seguida, salve seu script, vá para o início do arquivo de script, selecione getSurveyID na lista suspensa e clique no botão Iniciar.

Faça uma chamada de função getSurveyID

Isso fará uma solicitação GET para a SurveyMonkey e registrará a ID da primeira pesquisa com o mesmo título.

Vá para Exibir -> Registros. Salve esse ID!

Parabéns! Você acabou de fazer sua primeira chamada à API do SurveyMonkey! Se você acessar o painel do seu aplicativo, verá o número da sua chamada da API aumentar.

Criar um coletor para a pesquisa

Agora estamos prontos para criar automaticamente nosso colecionador! De acordo com a API do SurveyMonkey , precisamos postar uma solicitação POST no seguinte URL: https://api.surveymonkey.com/v3/surveys/{survey_id}/collectors . Substitua {survey_id} pelo ID que você obteve na etapa anterior.

Outro parâmetro obrigatório é o tipo. Você precisa especificar se o coletor é 'weblink' ou 'email'. Todos os outros parâmetros são opcionais. Naturalmente, você também precisaria passar o token de acesso para autorização.

Aqui vamos nos:

function createCollector () {

// Faça uma solicitação POST com uma carga útil JSON.
var data = {
"Tipo": "weblink"
};

var options = {
'método': 'post',
'headers': {'Authorization': 'bearer your_access_token'},
'contentType': 'aplicativo / json',
// Converta o objeto JavaScript em uma string JSON.
'payload': JSON.stringify (data),

};

var response = UrlFetchApp.fetch (' https://api.surveymonkey.com/v3/surveys/{survey_id}/collectors' , opções);
Logger.log (response.getContentText ());

}

Depois de executar essa função, você criou com sucesso um novo coletor para sua pesquisa! Viva! Vá para o seu Log, você pode ver a resposta HTTP enviada pelo SurveyMonkey. Ele contém detalhes sobre o coletor, como id, título e data de fechamento.

Você também pode especificar os detalhes ao criar o Collector passando os parâmetros opcionais listados na API.

Por intance:

var data = {
"Tipo": "weblink",
"Name": "My Web Collector",
“Thank_you_message”: “Obrigado por completar esta pesquisa!”,
“Close_date”: ”2018–05–30T22: 10: 00 + 00: 00”,
"Redirect_url": " https://google.com "
};

Preste atenção ao tipo de dados necessário. Se você passar um formato errado, ele lançará um erro de esquema inválido em você.

O mais complicado é o tipo de dados Date para “close_date”. Conforme especificado na API , as datas geralmente estão no formato AAAA-MM-DDTHH: MM: SS + HH: MM. Todas as strings de data estão implicitamente em UTC.

Indo além

Parabéns pela conclusão da sua primeira automação de colecionador bem-sucedida do SurveyMonkey! Agora você pode aproveitar o poder da automação para tornar sua distribuição de pesquisa indolor. Por exemplo, você pode modificar o script para criar 100 coletores com o mesmo padrão de nomenclatura em um único clique! Você pode distribuir automaticamente a pesquisa para a equipe de um departamento quando o chefe de departamento enviar um formulário de solicitação.

Não há mais trabalho manual graças à automação!