Tarefa do Serviço Web

Sobre a tarefa de serviço da Web

A tarefa Serviço Web é útil se você tem experiência com API e deseja acionador diferentes fluxos de trabalho no software Qualtrics ou em um serviço Web externo quando o entrevistado termina a pesquisa. Por exemplo, se sua pesquisa coletar as informações de contato do entrevistado, uma tarefa de serviço da Web poderá usar a chamada da API de criação de contato para adicionar o entrevistado a uma lista de contatos.

Também recomendamos a visita a estas páginas relacionadas a serviços da Web para mais assistência e background:

• Hub do desenvolvedor da Qualtrics
• Métodos de Web Service
• Documentação API
• Transferência de informações por meio de cadeias de consulta
• Texto transportado

Configuração de uma tarefa de serviço da Web

Dependendo de como você prefere formatar seus parâmetros do corpo, a configuração será ligeiramente diferente. Se você estiver usando o formato JSON ou XML, insira seu corpo na seção Corpo. Se você preferir codificado em URL, pode adicionar parâmetros como uma query string ao campo URL.

1. Crie um workflow (ou selecione um existente) em seu projeto ou na página Fluxos de trabalho independentes.
   
2. Certifique-se de que você está na seção Seus workflows.
3. Clique em Criar um fluxo de trabalho.
4. Determine a programação ou o evento que aciona sua tarefa. (Consulte uma comparação.)
5. Clique em Adicionar tarefa e selecione Serviço web.
   
6. Escolha seu método de autenticação. Suas opções incluem:
   
   • Autenticado: execute uma solicitação de serviço Web autenticada. Suas opções de autenticação incluem básico (com senha e nome de usuário), chave de API e OAuth.
   • Não autenticado: execute uma solicitação de serviço da Web sem autenticação.
7. Clique em Seguinte.
8. Se você tiver selecionado uma solicitação autenticada, selecione suas credenciais de autorização na lista ou clique em Adicionar conta de usuário para adicionar novas credenciais. Consulte Adicionar credenciais de autorização para mais informações.
   
   Qdica: Você poderá selecionar as credenciais adicionadas anteriormente ou as credenciais adicionadas por um Administrador da marca na guia Extensões.
9. Clique em Seguinte.
10. Se você tiver uma solicitação no formato curl, poderá importá-la para configurar automaticamente seu serviço web. Veja o Usando comandos Curl seção para mais detalhes.
    
11. Se desejar, adicione um Resumo da tarefa na parte superior da tarefa. Esta é uma descrição explicando a meta da tarefa.
12. Escolha o método Request do seu serviço Web. Consulte Métodos de Web Service para obter mais informações sobre cada método.
    
    Qdica: Se você estiver usando a API da Qualtrics, a documentação informará que tipo de solicitação usar.
    Atenção: as tarefas do Web Service não permitem redirecionamentos de URL para solicitações não GET. Só é permitido um redirecionamento para solicitações GET.
13. Insira o URL para sua solicitação.
    Qdica: você pode limitar os domínios aos quais a tarefa de serviço da Web pode se conectar especificando os domínios nas configurações do seu domínio de extensão.
14. Se desejar, clique em Adicionar cabeçalho para adicionar um cabeçalho. Indique a Chave e o Valor. Para remover um cabeçalho, clique no ícone da lixeira ao lado do cabeçalho.
    Qdica: Use o ícone de texto transportado, {a}, para inserir texto transportado para obter valores de respostas da pesquisa ou tarefas anteriores no fluxo de trabalho.
    Atenção: se estiver usando a API da Qualtrics, você deve incluir seu token de API por meio do cabeçalho. Consulte Adicionando um cabeçalho para solicitações da API da Qualtrics para obter mais informações.
15. Se você escolheu postar, colocar ou corrigir, você precisará escolher o formato do seu corpo. As opções incluem JSON, URL codificado, XML e Texto simples.
    
    
16. Determine como você deseja especificar o corpo da sua solicitação. Você pode adicionar o corpo como pares de valores-chave ou texto livre.
17. Se você tiver selecionado pares chave-valor, adicione a Chave e o respectivo Valor associado. Clique em Adicionar par de valores-chave para adicionar parâmetros adicionais.
    Atenção: para solicitações POST, PUT e PATCH, você deve especificar um tipo de dados para cada par chave-valor.
18. Selecione um Tipo de dados.
    • Booleano: selecione este tipo de dados se seus dados tiverem um dos dois valores possíveis.
    • JSON: selecione este tipo de dados se seus dados estiverem no formato JSON.
    • Número: selecione este tipo de dados se seus dados forem numéricos.
    • String: selecione este tipo de dados se seus dados estiverem em formato de texto.
    • Padrão do sistema: selecione este tipo de dados se você quiser usar o tipo de dados nativos para seus dados. Se não for possível encontrar um tipo de dados, isso será predefinido para o tipo String.
      Qdica: recomendamos selecionar um dos outros tipos de dados para garantir que seus dados sejam moldados corretamente.
      Atenção: os pares de valores-chave que foram configurados antes de 16 de setembro de 2022 terão um tipo de dados Padrão do sistema.
    Qdica: O campo Tipo de dados só está disponível quando você seleciona pares JSON e Valor-chave nas etapas 13-14.
19. Selecione o que acontece se o tipo de dados não puder ser convertido.
    • Não lançar um tipo de dados e marcá-lo como erro: se o tipo de dados não puder ser convertido, nenhum tipo de dados será convertido e a tarefa falhará. Isso pode ser visto na guia Histórico da execução.
    • Cast o tipo de dados para padrão do sistema: se o tipo de dados não puder ser moldado, o tipo de dados será definido como Padrão do sistema.
20. Se você tiver selecionado Texto livre, insira seus parâmetros de corpo no seu formato selecionado.
    
    Atenção: você não deve deixar este campo em branco ou ter chaves sem valores. Em vez disso, não inclua o campo ou insira o termo “nulo” para indicar valores vazios. Recomendamos a exclusão do campo.
    Atenção: As tarefas de serviço da Web não oferecem suporte a comentários no momento.
21. Para testar seu serviço Web, clique em Executar teste.
    
    Qdica: Depois de clicar em Executar teste, o resultado da sua solicitação será exibido, informando se ela foi bem-sucedida ou não e o JSON ou XML resultante, se foi bem-sucedido.
22. Clique em Adicionar caminho personalizado para adicionar caminhos JSON ou XML. Esses caminhos permitem que você use os resultados do seu serviço da Web em texto transportado para serem usados com outras tarefas em seu fluxo de trabalho, como uma tarefa de código. Se você testou seu serviço Web, pode ter valores automaticamente aqui, pois a Qualtrics os retirará automaticamente dos resultados.
    Qdica: Clique em Adicionar caminho personalizado para adicionar outros caminhos ou clique na lixeira ao lado de um caminho para excluí-la.
23. Ao concluir a configuração do fluxo de trabalho, clique em Salvar.

Adicionar credenciais de autorização

Esta seção aborda como adicionar credenciais de autorização para a tarefa de Web Service. Você pode adicionar credenciais usando o método Básico, Chave API ou OAuth 2.0. Para adicionar credenciais, clique em Adicionar conta de usuário na janela de seleção de credenciais.

Básico

A autenticação padrão requer que você efetue o logon com o nome de usuário e a senha da sua conta.

1. Dê um nome às suas credenciais. Isso é apenas para fins organizacionais.
2. Selecione Básico como o tipo de conexão.
3. Insira o Nome de usuário necessário para autenticação.
4. Insira a Senha para autenticação.
5. Clique em Conectar conta.

Chave API

A autenticação de chave API permite que você autentique usando um token de API estático.

1. Dê um nome à sua conta. Isso é apenas para fins organizacionais.
2. Escolha a chave de API como o tipo de conexão.
3. Insira o Token de API usado para autenticação.
4. Clique em Conectar conta.

OAuth 2.0

A autorização OAuth2.0 remove a necessidade de utilizar tokens de API estáticos ou nome de usuário e senha básicos para integrar a plataformas de terceiros. A tarefa de serviço Web suporta dois tipos diferentes de autorização OAuth2.0: código de autorização e credenciais de cliente.

Você pode utilizar a autorização OAuth 2.0 para se integrar perfeitamente com muitas plataformas de terceiros. A implementação do serviço Web da Qualtrics segue a especificação oficial do OAuth. No entanto, alguns sistemas externos podem ter configurações ligeiramente diferentes, levando a incompatibilidades com autorização OAuth2.0 na tarefa de Web Service.

As seguintes integrações são alguns exemplos que foram totalmente verificados para trabalhar com o OAuth2.0:

• Salesforce usando o método do código de autorização.
• Jira utilizando o método do código de autorização.
• Zoom usando o método do código de autorização.

Para autenticar usando OAuth 2.0:

1. Dê um nome à sua conta. Isto é somente para fins organizacionais.
2. Selecione OAuth como tipo de conexão.
3. Escolha seu tipo de Concessão ou como o token de acesso é recuperado. Você pode escolher:
   • Código de Autorização
   • Credenciais de cliente
4. Insira o ID do cliente e a Chave secreta do cliente.
5. Insira o ponto de acesso de token.
6. Se você tiver selecionado o código de autorização como o tipo de subsídio público, insira o ponto de acesso de autorização.
7. Clique em Conectar conta.

Renomeando & removendo credenciais

Para editar o nome da credencial, clique nos três pontos ao lado da conta. Para remover credenciais, clique em Remover conta.

Adicionando um cabeçalho para solicitações da API da Qualtrics

Ao usar a API da Qualtrics, você deve incluir seu token de API como cabeçalho no serviço da Web.

1. Configure sua tarefa de serviço da Web, selecione suas credenciais e escolha sua solicitação.
   
2. Na seção Cabeçalhos, insira X-API-TOKEN como a Chave.
3. Para o valor, clique no ícone de texto transportado, {a}.
4. Selecione suas credenciais na lista.
   

TLS mútuo

A segurança de camada de transporte mútua (mTLS) é uma camada opcional adicional de segurança sobre mecanismos de autenticação API padrão (como token de API ou OAuth). O TLS mútuo garante que a pessoa que se conecta a uma API/serviço da Web e o próprio API/serviço da Web tenham tráfego seguro e criptografado em ambas as direções. Assim que o mTLS estiver ativado, todas as solicitações devem apresentar o certificado do cliente correto para que as solicitações tenham êxito. Se um chamador fizer uma solicitação utilizando um certificado do client inválido ou em falta, a API que está tentando chamar irá bloquear a solicitação.

Requisitos

Cada serviço varia se ele suporta mTLS e em que formato(s) ele fornece informações-chave no. Só temos a garantia de oferecer suporte ao mTLS para serviços que atendam aos nossos requisitos:

• Fornecer uma chave privada
• A chave privada pode ser formatada em PKCS8
• Fornecer um certificado
• O certificado pode ser formatado em X.509

As APIs públicas da Qualtrics suportam mTLS conforme descrito acima.

O mTLS só é suportado para serviços da Web autenticados criados em fluxos de trabalho. Todos os três métodos de autenticação são suportados (Básico, Chave API e OAuth2.0).

Adicionando mTLS

1. Crie sua tarefa de serviço da Web.
   
2. Selecione Autenticado.
   
3. Clique em Seguinte.
4. Adicione uma conta de usuário.
   
   Qdica: Um Administrador da marca pode se conectar a uma conta usando a página Extensões.
   
5. Selecione um tipo de conexão e preencha suas credenciais.
   
6. Selecione Ativar mTLS.
7. A chave privada pode ser considerada como o identificador exclusivo do cliente que está tentando se conectar. Este valor deve estar no formato PKCS8.
   Qdica: Se sua chave estiver em um formato diferente, use outro programa para alterar esse formato.
   Qdica: Se você está planejando usar a API da Qualtrics com seu serviço web, consulte nossa Documentação da API no mTLS. Esta documentação mostrará como puxar a chave privada. Ao colar o valor no Qualtrics, você precisará incluir traços que dizem “começar chave privada” e “terminar chave privada”.
8. A chave pública é o certificado mTLS. Este valor precisa estar no formato X.509.
   Qdica: Se você está planejando usar a API da Qualtrics com seu serviço web, consulte nossa Documentação da API no mTLS. Esta documentação mostrará a você como obter o certificado. Ao colar o valor no Qualtrics, você precisará incluir traços que dizem “certificado inicial” e “certificado final”.
9. Quando terminar, clique em Conectar conta.
10. Continue com a configuração do seu serviço Web.

Usando comandos Curl

Os comandos curl são uma das muitas maneiras de fazer solicitações HTTP e são uma ferramenta valiosa para passar informações de um lado para o outro por meio de URLs. Você pode importar um comando curl enquanto configura sua tarefa para preencher automaticamente diferentes configurações de serviço web.

Muitos documentos de API geralmente fornecem exemplos de curl que você pode usar. Poder copiar e importar esses comandos pode tornar a configuração do serviço web muito mais rápida e fácil.

Para alguns exemplos de solicitações curl, veja à direita em cada um destes documentos de API :

• Obter Lista de discussão
• Criar Distribuição de Lembrete
• Atualizar transação de contato
• Lista usuários no grupo

Para uma solicitação GET, o comando curl pode ser tão simples quanto curl https://api.example.com/parameters . Para comandos curl que não são tão simples quanto este, forneceremos alguns parâmetros comuns.

Parâmetros de comando Curl suportados

Aqui estão alguns dos parâmetros curl que a tarefa do serviço web Qualtrics suporta:

Parâmetros comuns de cabeçalho

Acima, mencionamos que você pode usar comandos curl para definir cabeçalhos. Os cabeçalhos atendem a vários propósitos na comunicação HTTP, como fornecer informações sobre a solicitação e controlar a autenticação. Os cabeçalhos específicos que você usa dependem dos requisitos do aplicativo ou da API que você está usando.

Aqui estão alguns exemplos de parâmetros de cabeçalho:

Parâmetros não suportados

Quaisquer parâmetros de curl não listados acima são não suportado. Aqui estão alguns exemplos de formatos de comando curl que as tarefas do serviço web Qualtrics não suportam:

• --biscoito para enviar cookies com a solicitação.
• --EU ou --localização para seguir redirecionamentos.
• --tempo-máximo para definir o tempo máximo de solicitação.
• --o ou --saída para salvar a resposta em um arquivo.
• --inseguro para permitir conexões inseguras.
• --UM ou --agente-usuário para especificar o agente do usuário.

Importando comandos Curl

1. Durante a configuração da tarefa do serviço da web, clique em Importar cURL .
   
2. Cole seu comando curl na caixa.
   
   Atenção : Certifique-se de incluir seu método HTTP na sua solicitação curl, especialmente se estiver copiando um comando curl de outra plataforma.
   Qdica: Fique atento às partes da solicitação que você precisa preencher com suas próprias informações. Por exemplo, na captura de tela acima, você substituiria “Chave API ” por sua token de API .

   Qdica: Você pode adicionar um comando em uma única string ou pode marcar quebras de linha usando o caractere de escape ( \ ). Nós fazemos não suporta outras fugas de linha (por exemplo, ^ ). Aqui está um exemplo de um comando curl com caracteres de escape suportados:

   enrolar https://www.google.com/accounts/test \
    -d accountType=GOOGLE \
    -d fonte=Google-cURL-Exemplo \
    -d serviço=lh2

3. Clique em Importar.
4. Os campos do serviço web serão preenchidos automaticamente.

Perguntas frequentes