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 da API
• Transmissão de informações por meio de cadeias de caracteres de consulta
• Texto transportado

Qdica: Esta página contém referências à API do Qualtrics, que é um característica que requer permissão especial para ser acessado. Se estiver interessado em obter acesso a esse característica, entre em contato com o administrador Marca para obter mais informações.

Atenção: A configuração de um serviço da Web geralmente requer conhecimentos avançados de programação. Embora nossa equipe de suporte tenha prazer em ajudar com os aspectos básicos da inserção de informações no serviço da Web, não podemos oferecer suporte aos aspectos de programação.

Atenção: As tarefas de serviço da Web são compatíveis apenas com os seguintes tipos de conteúdo: URL-Encoded, XML, JSON e Plain Text.

Qdica: Você está configurando seu serviço da Web a partir de um documento de API? Sua configuração pode ser muito mais rápida se você importar um comando curl.

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

Atenção: A saída da chamada que está sendo feita em sua tarefa serviço da Web tem um limite de 1 MB.

Qdica: você pode usar o AI Assistant para ajudar a configurar a tarefa de serviço da Web. Para obter mais informações, consulte Uso do AI Assist para configuração de Tarefa.

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.

Crie um fluxo de trabalho (ou selecione um existente) em seu projeto ou na página de fluxos de trabalho autônomos.

---

×

close

Verifique se você está na seção Seus fluxos de trabalho.

Clique em Criar um fluxo de trabalho.

Determine a programação ou o evento que aciona sua tarefa.(Veja uma comparação. )

Clique em Adicionar tarefa e selecione WebService.

---

×

close

Escolha seu método de autenticação. Suas opções incluem:

---

×

close

• 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.

Clique em Seguinte.

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.

---

×

close

Qdica: você poderá selecionar quaisquer credenciais que tenha adicionado anteriormente ou credenciais adicionadas por um administrador Marca na guia Extensões.

Clique em Avançar.

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.

---

×

close

Se desejar, adicione um Resumo Tarefa na parte superior de sua tarefa. Essa é uma descrição que explica o objetivo da tarefa.

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.

---

×

close

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.

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.

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.

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.

---

×

close

Determine como você deseja especificar o corpo de sua solicitação. Você pode adicionar o corpo como pares de valores-chave ou texto livre.

Qdica: o número máximo de caracteres para pares de valores-chave e texto livre é 75.000.

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.

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.

  

  Qdica: certifique-se de que os dados inseridos sejam um JSON válido. Ao usar texto transportado, certifique-se de que os caracteres especiais não estejam incluídos.

• 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.

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.

Se você selecionou Texto livre, insira os parâmetros do corpo no formato selecionado.

---

×

close

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.

Para testar seu serviço da Web, clique em Run test (Executar teste).

---

×

close

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.

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.

Atenção: Os dados de uma tarefa com falha não podem ser canalizados para outra tarefa. O texto transportado será exibido como um valor nulo.

Quando terminar de configurar seu fluxo de trabalho, clique em Salvar.

Qdica: as tarefas de serviço da Web têm um tempo limite de 16 segundos. Se uma chamada ao serviço da Web demorar mais de 10 segundos, o fluxo de trabalho falhará.

Uso do assistente de IA para configuração de Tarefa

Atenção: Você só pode usar o mapeamento automático se um Administrador Marca tiver ativado a permissão Assistência de IA na configuração de fluxos de trabalho para sua organização na guia Admin.

O AI Assistant pode configurar a integração da API em tarefas de serviço da Web, lendo a documentação API disponível publicamente e configurando a tarefa automaticamente.

Criar um fluxo de trabalho com uma tarefa Web Service .

Escolha seu método de autenticação. Para obter mais informações, consulte Configuração de uma Tarefa de serviço da Web.

Clique em Try AI Assistant.

---

×

close

Selecione o serviço da Web.

Descreva a intenção ou a solicitação da chamada à API.

Clique em Generate draft (Gerar rascunho).

Qdica: se o AI Assistant não conseguir gerar um rascunho, edite a solicitação e tente novamente.

Revise a configuração da API.

---

×

close

Para testar seu serviço da Web, clique em Run test (Executar teste).

---

×

close

Clique em Adicionar caminho personalizado para adicionar caminhos JSON ou XML. Para obter mais informações, consulte Configuração de uma Tarefa de serviço da Web.

Clique em Salvar.

Qdica: Embora tenhamos proteções em vigor e estejamos continuamente refinando nossos produtos, a inteligência artificial pode, às vezes, gerar resultados imprecisos, incompletos ou desatualizados. Antes de usar qualquer resultado dos recursos de IA da Qualtrics, você deve analisá-lo para verificar sua precisão e garantir que ele seja adequado para seu caso de uso. Os resultados dos recursos de IA da Qualtrics não substituem a revisão humana ou a orientação profissional.

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.

Qdica: todos os tipos de conexão são compatíveis com o mTLS. Para saber mais, consulte a seção TLS mútuo.

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.

---

×

close

Chave API

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

---

×

close

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.

Qdica: Ao criar uma conexão OAuth, o URL de redirecionamento será https://{dataCenter}.qualtrics.com/oauth-client-service/redirect, em que {dataCenter} representa o valor associado à sua conta. Consulte esta página para obter mais detalhes sobre como localizar o data center de sua conta.

Para autenticar usando o OAuth 2.0:

---

×

close

Qdica: para usuários que configuram credenciais do Google OAuth, inclua o seguinte parâmetro no final do seu ponto de extremidade do token: “?prompt=consent.” Se você tiver parâmetros de consulta existentes, o ponto de interrogação não será necessário.

Qdica: Se estiver tendo problemas para se conectar ao Snowflake, verifique se os intervalos de IP do Qualtrics estão na lista de permissões.

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.

---

×

close

Qdica: você só pode renomear ou remover credenciais que você mesmo adicionou.

Aviso: Tenha cuidado ao excluir credenciais! Todos os fluxos de trabalho que usam as credenciais deixarão de funcionar quando as credenciais forem excluídas.

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.

Configure sua tarefa de serviço da Web, selecione suas credenciais e escolha sua solicitação.

---

×

close

Na seção Headers (Cabeçalhos), insira X-API-TOKEN como a chave.

Para o valor, clique no ícone de texto transportado, {a}.

Selecione suas credenciais na lista.

---

×

close

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

Crie sua tarefa de serviço da Web.

---

×

close

Selecione Authenticated (Autenticado).

---

×

close

Clique em Seguinte.

Adicione uma conta usuário.

---

×

close

Qdica: um administrador Marca pode se conectar a uma conta usando a página Extensões.

---

×

close

Selecione um tipo de conexão e preencha suas credenciais.

---

×

close

Selecione Habilitar mTLS.

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)

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”

Quando terminar, clique em Connect Conta (Conectar conta ).

Prossiga com a configuração de seu serviço da Web.

Qdica: a validade das suas chaves mTLS não pode ser testada até que você execute uma chamada de API por meio do seu serviço da Web, portanto, você não verá uma mensagem de erro nesta página se tiver inserido as chaves incorretamente. Tente testar o serviço da Web antes de colocar seu fluxo de trabalho em funcionamento.

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 https://api.example.com/parameters. Para comandos curl que não são tão simples como esse, forneceremos alguns parâmetros comuns.

Qdica: se você estiver editando uma tarefa de serviço da Web existente, todos os comandos curl que você importar substituirão as configurações anteriores.

Qdica: se você estiver interessado em aprender mais sobre curl do que o que abordamos abaixo, recomendamos a leitura de um recurso fora do suporte da Qualtrics, como a documentação da IBM.

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.

Qdica: se você tentar importar um comando curl com parâmetros não suportados, será exibida uma mensagem de erro listando os parâmetros não suportados que você usou. Você terá a opção de continuar importando seu comando curl com os parâmetros não suportados removidos.

Importação de comandos Curl

Durante a configuração tarefa serviço da Web, clique em Importar cURL.

---

×

close

Cole seu comando curl na caixa.

---

×

close

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

Clique em Importar.

Os campos do serviço da Web serão preenchidos automaticamente.

Qdica: recomendamos verificar novamente os campos antes de ativar o fluxo de trabalho.