Tarefa do Serviço Web

Sobre a Tarefa serviço da Web

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

Também recomendamos visitar essas páginas relacionadas ao serviço da Web para obter mais assistência e informações básicas:

• Centro de desenvolvedores Qualtrics
• Métodos de serviço da Web
• Documentação API
• Transmissão de informações por meio de cadeias de caracteres de consulta
• Texto transportado

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

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

1. Crie um fluxo de trabalho (ou selecione um existente) em seu projeto ou na página de fluxos de trabalho autônomos.
   
2. Verifique se você está na seção Seus fluxos de trabalho.
3. Clique em Criar um fluxo de trabalho.
4. Determine a programação ou o evento que aciona sua tarefa.(Veja uma comparação. )
5. Clique em Adicionar tarefa e selecione WebService.
   
6. Escolha seu método de autenticação. Suas opções incluem:
   
   • Autenticado: Executa uma solicitação de serviço da Web autenticada. Suas opções de autenticação incluem básica (com uma senha e nome de usuário), chave API e OAuth.
   • Não autenticado: Executa uma solicitação de serviço da Web sem autenticação.
7. Clique em Seguinte.
8. Se você selecionou uma solicitação autenticada, selecione suas credenciais de autorização na lista ou clique em Add User Conta (Adicionar conta de usuário) para adicionar novas credenciais. Consulte Adição de credenciais de autorização para obter mais informações.
   
   Qdica: você poderá selecionar quaisquer credenciais que tenha adicionado anteriormente ou credenciais adicionadas por um administrador Marca na guia Extensões.
9. Clique em Avançar.
10. Se você tiver uma solicitação formatada em curl, poderá importá-la para configurar automaticamente seu serviço da Web. Consulte a seção Usando comandos Curl para obter detalhes.
    
11. Se desejar, adicione um Resumo Tarefa na parte superior de sua tarefa. Essa é uma descrição que explica o objetivo da tarefa.
12. Escolha o método Request de seu serviço da Web. Consulte Métodos de serviço da Web para obter mais informações sobre cada método.
    
    Qdica: se você estiver usando a API do Qualtrics, a documentação informará que tipo de solicitação deve ser usada.
    Atenção: As tarefas do WebService não permitem nenhum redirecionamento de URL para solicitações não-GET. Somente um redirecionamento é permitido para solicitações GET.
13. Digite o URL de 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 de domínio de extensão.
14. Se desejar, clique em Add header (Adicionar cabeçalho ) para adicionar um cabeçalho. Especifique a chave e o valor. Para remover um cabeçalho, clique no ícone lixeira lixeira avançar do cabeçalho.
    Qdica: use o ícone de texto transportado, {a}, para inserir texto transportado para extrair valores das respostas pesquisa ou de tarefas anteriores no fluxo de trabalho.
    Atenção: Se estiver usando a API do Qualtrics, você deve incluir seu token de API no cabeçalho. Consulte Adição de um cabeçalho para solicitações API do Qualtrics para obter mais informações.
15. Se você escolheu post, put ou patch, precisará escolher o formato do seu corpo. As opções incluem JSON, codificado por URL, XML e Texto simples.
    
    
16. Determine como você deseja especificar o corpo de sua solicitação. Você pode adicionar o corpo como pares de valores-chave ou texto livre.
17. Se você selecionou pares chave-valor, adicione a chave e o valor associado. Clique em Add key-value pair (Adicionar par chave-valor ) para adicionar outros parâmetros.
    Atenção: Para solicitações POST, PUT e PATCH, você deve especificar um tipo de dados para cada par de valores-chave.
18. Selecione um tipo de dados.
    • Booleano: Selecione esse tipo de dados se seus dados tiverem um de dois valores possíveis.
    • JSON: selecione esse tipo de dados se seus dados estiverem no formato JSON.
    • Número: Selecione esse tipo de dados se seus dados forem numéricos.
    • String (Cadeia de caracteres): Selecione esse tipo de dados se seus dados estiverem em formato de texto.
    • Padrão do sistema: Selecione esse tipo de dados se quiser usar o tipo de dados nativo para seus dados. Se não for possível encontrar um tipo de dados, o padrão será o tipo String.
      Qdica: recomendamos selecionar um dos outros tipos de dados para garantir que seus dados sejam convertidos corretamente.
      Atenção: Os pares de valores-chave que foram configurados antes de 16 de setembro de 2022 terão um tipo de dados de Padrão do sistema.
    Qdica: o campo Data type (Tipo de dados ) só está disponível quando você seleciona JSON e Key-value pairs (Pares de valores-chave ) nas etapas 13-14.
19. Selecione o que acontecerá se o tipo de dados não puder ser convertido.
    • Não converta um tipo de dados e sinalize como um 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 Run History (Histórico de execução ).
    • Converter o tipo de dados para o padrão do sistema: se o tipo de dados não puder ser convertido, o tipo de dados será definido como Padrão do sistema.
20. Se você selecionou Texto livre, insira os parâmetros do corpo no formato selecionado.
    
    Atenção: Você não deve deixar esse campo vazio ou ter chaves sem valores. Em vez disso, não inclua o campo ou insira o termo “null” para indicar valores vazios. Recomendamos excluir o campo.
    Qdica: se uma tarefa de serviço da Web encontrar um corpo JSON inválido, a tarefa não falhará. Em vez disso, o JSON inválido será convertido em uma cadeia de caracteres e salvo como uma propriedade “text” em um novo objeto JSON. Dessa forma, você poderá ver o texto inválido quando a tarefa terminar de ser processada.
    Atenção: Atualmente, as tarefas de serviço da Web não aceitam comentários.
21. Para testar seu serviço da Web, clique em Run test (Executar teste).
    
    Qdica: depois de clicar em Run test (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 tiver sido bem-sucedida.
22. Clique em Adicionar caminho personalizado para adicionar caminhos JSON ou XML. Esses caminhos permitem que você use resultados do seu serviço da Web em texto transportado, para ser usado com outras tarefas em seu fluxo de trabalho, como uma tarefa código. Se você testou seu serviço da Web, poderá ter valores automaticamente aqui, pois o Qualtrics os extrairá automaticamente dos resultados.
    Qdica: clique em Adicionar caminho personalizado para adicionar outros caminhos ou clique na lixeira avançar de um caminho para excluí-lo.
23. Quando terminar de configurar seu fluxo de trabalho, clique em Salvar.

Adição de credenciais de autorização

Esta seção aborda como adicionar credenciais de autorização para a tarefa serviço da Web. Você pode adicionar credenciais usando o método Basic, API Key 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 básica exige que você faça login 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. Escolha Básico como o tipo de conexão.
3. Digite o nome de usuário necessário para a autenticação.
4. Digite a senha para autenticação.
5. Clique em Conectar conta.

Chave API

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

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

OAuth 2.0

A autorização OAuth2.0 elimina a necessidade de usar tokens API estáticos ou nome de usuário e senha básicos para integração com plataformas de terceiros. A tarefa de serviço da Web é compatível com dois tipos diferentes de autorização OAuth2.0: código de autorização e credenciais do cliente.

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

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

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

Para autenticar usando o OAuth 2.0:

1. Dê um nome à sua conta. Isso é apenas para fins organizacionais.
2. Escolha OAuth como o 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. Digite o ID do cliente e o segredo do cliente.
5. Digite o ponto de extremidade do token.
6. Se você selecionou o código de autorização como o tipo de concessão, insira o ponto de extremidade Authorization (Autorização).
7. Clique em Conectar conta.

Renomear e registrar; remover credenciais

Para editar o nome de sua credencial, clique nos três pontos ao avançar da conta. Para remover as credenciais, clique em Remover conta.

Adição de um cabeçalho para solicitações API do Qualtrics

Ao usar a API do Qualtrics, você deve incluir seu token de API como um cabeçalho em seu 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 Headers (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 da camada de transporte mútuo (mTLS) é uma camada adicional e opcional de segurança sobre os mecanismos de autenticação API padrão (como API Token ou OAuth). O TLS mútuo garante que tanto a pessoa que se conecta a uma API da Web quanto a própria API da Web tenham tráfego seguro e criptografado em ambas as direções. Quando o mTLS estiver ativado, todas as solicitações deverão apresentar o certificado de cliente correto para que sejam bem-sucedidas. Se um chamador fizer uma solicitação usando um certificado de cliente inválido ou ausente, a API que ele está tentando chamar bloco a solicitação.

Requisitos

Cada serviço varia em relação ao suporte ao mTLS e ao(s) formato(s) em que fornece informações importantes. Só temos garantia de suporte a 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 do Qualtrics suportam mTLS conforme descrito acima.

mTLS é suportado apenas para serviços da Web autenticados criados em fluxos de trabalho. Todos os três métodos de autenticação são compatíveis (básico, chave API e OAuth2.0).

Adição de mTLS

1. Crie sua tarefa de serviço da Web.
   
2. Selecione Authenticated (Autenticado).
   
3. Clique em Seguinte.
4. Adicione uma conta usuário.
   
   Qdica: um administrador 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 Habilitar mTLS.
7. A chave privada pode ser considerada como o identificador exclusivo do cliente que está tentando se conectar. Esse valor precisa estar no formato PKCS8.
   Qdica: se sua chave estiver em um formato diferente, você poderá usar outro programa para alterar esse formato.
   Qdica: se estiver planejando usar a API do Qualtrics com seu serviço da Web, consulte nossa documentação API sobre mTLS. Esta documentação mostrará a você como obter a chave privada. Ao colar o valor no Qualtrics, você precisará incluir traços que digam “begin private key” (início da chave privada) e “end private key” (fim da chave privada)
8. A chave pública é o certificado mTLS. Esse valor precisa estar no formato X.509.
   Qdica: se estiver planejando usar a API do Qualtrics com seu serviço da Web, consulte nossa documentação API sobre mTLS. Esta documentação mostrará a você como obter o certificado. Ao colar o valor no Qualtrics, você precisará incluir traços que indiquem “início do certificado” e “fim do certificado”
9. Quando terminar, clique em Connect Conta (Conectar conta ).
10. Prossiga com a configuração de seu serviço da Web.

Uso de 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 para frente e para trás por meio de URLs. Você pode importar um comando curl enquanto estiver configurando sua tarefa para preencher automaticamente diferentes configurações de serviço da Web.

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

Para ver alguns exemplos de solicitações curl, dê uma olhada à direita em cada um desses documentos API:

• Obter Lista de correio eletrônico
• Criar Distribuição Lembrete
• Atualizar Transação Contato
• Lista usuários no grupo

Para uma solicitação GET, o comando curl pode ser tão simples quanto curl api Para comandos curl que não são tão simples como esse, forneceremos alguns parâmetros comuns.

Parâmetros do comando Curl suportados

Aqui estão alguns dos parâmetros curl suportados pela tarefa de serviço da Web do Qualtrics:

Parâmetros comuns do cabeçalho

Acima, mencionamos que você pode usar comandos curl para definir cabeçalhos. Os cabeçalhos têm várias finalidades na comunicação HTTP, como o fornecimento de informações sobre a solicitação e o controle da 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

Os parâmetros curl não listados acima não são compatíveis. Aqui estão alguns exemplos de formatos de comando curl que as tarefas de serviço da Web da Qualtrics não suportam:

• –-cookie para enviar cookies com a solicitação.
• –-L ou --location para os redirecionamentos seguintes.
• –-max-time para definir o tempo máximo de solicitação.
• –-o ou --output para salvar a resposta em um arquivo.
• –-insecure para permitir conexões inseguras.
• –-A ou --user-agent para especificar o agente do usuário.

Importação de comandos Curl

1. Durante a configuração tarefa 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 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 “API Key” pelo seu token de API.

   Qdica: você pode adicionar um comando em uma única cadeia de caracteres ou marcar quebras de linha usando o caractere de escape ( \ ). Não oferecemos suporte a outros escapes de linha (por exemplo, ^ ). Aqui está um exemplo de um comando curl com caracteres de escape compatíveis:

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

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

Perguntas frequentes