Tarefa do Serviço Web

Sobre a tarefa de serviço da Web

The Web Service task is useful if you are experienced with API and would like to trigger different workflows within the Qualtrics software, or to an external web service, when the respondent finishes the survey. 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. If you’ve got a curl-formatted request, you can import it to automatically set your web service up. See the Using Curl Commands section for details.
    
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.
    Atenção: para solicitações POST, PUT e PATCH, você deve especificar um tipo de dados para cada par chave-valor.
    Atenção: as tarefas do Web Service não suportam atualmente comentários/texto no corpo que contém sequências de escape.
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.
    
    
    Qdica: O texto simples só pode ser especificado como texto livre. Ao usar a opção de texto livre JSON, as entradas não têm escape. Isso significa que, por exemplo, uma entrada de texto transportado contendo aspas duplas ou caracteres de nova linha (exemplo: \n) fará com que o corpo JSON se torne inválido e não seja executado corretamente. Uma alternativa a isso é usar a opção de pares chave-valor ou usar uma tarefa de código para limpar ou escapar do texto a ser injetado na tarefa do serviço Web.
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.
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.
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.

Using Curl Commands

Curl commands are one of many ways you can make HTTP requests, and are a valuable tool in passing information back and forth through URLs. You can import a curl command while you’re setting up your task to auto-populate different web service configurations.

Many API docs often provide curl examples you can use. Being able to copy and import these commands can thus make web service setup much quicker and easier.

For some examples of curl requests, look at the right on each of these API docs:

• Get Mailing List
• Create Reminder Distribution
• Atualizar transação de contato
• List Users in Group

For a GET request, the curl command can be as simple as curl https://api.example.com/parameters. For curl commands that aren’t as simple as this, we’ll provide some common parameters.

Supported Curl Command Parameters

Here are some of the curl parameters the Qualtrics web service task supports:

Common Header Parameters

Above, we mentioned you can use curl commands to define headers. Headers serve various purposes in HTTP communication, such as providing information about the request and controlling authentication. The specific headers you use depend on the requirements of the application or API you’re using.

Here are some examples of header parameters:

Unsupported Parameters

Any curl parameters not listed above are not supported. Here are a few examples of curl command formats Qualtrics web service tasks do not support:

• --cookie to send cookies with the request.
• --L or --location for following redirects.
• --max-time for setting maximum request time.
• --o or --output for saving response to a file.
• --insecure to allow insecure connections.
• --A or --user-agent to specify user agent.

Importing Curl Commands

1. During your web service task setup, click Import cURL.
   
2. Paste your curl command in the box.
   
   Attention: Make sure you include your HTTP method in your curl request, especially if you’re copying a curl command from another platform.
   Qtip: Keep an eye out for parts of the request you need to fill out with your own information. For example, in the screenshot above, you’d replace “API Key” with your API token.

   Qtip: You can add a command in one single string, or you can mark line breaks using the escape character ( \ ). We do not support other line escapes (for example, ^ ). Here’s an example of a curl command with supported escape characters:

   curl https://www.google.com/accounts/test \
   -d accountType=GOOGLE \
   -d source=Google-cURL-Example \
   -d service=lh2

3. Clique em Importar.
4. Web service fields will be filled automatically.

Perguntas frequentes