Serviço Web

Sobre os serviços da Web

Às vezes, você pode querer incluir recursos mais complexos em seu pesquisa. Talvez queira incluir as 10 principais manchetes de um site de notícias em seu pesquisa, ou automatizar a distribuição de um segundo pesquisa a ser enviado por e-mail aos respondentes de um primeiro pesquisa exatamente duas horas depois. Um serviço da Web permitiria que você fizesse exatamente isso, fazendo solicitações a um URL designado.

Adição de um serviço da Web

1. Ao editar o pesquisa, clique no ícone Fluxo da pesquisa na barra de navegação esquerda.
   
2. Clique em Adicionar abaixo ou Adicionar um novo elemento aqui.
   
3. Selecione Web Service.
4. No campo URL, cole o URL de seu serviço da Web externo.
   
   Qdica: você pode usar texto transportado para passar as informações pesquisa para o URL do endpoint por meio de cadeias de consulta.
5. Selecione um método para seu serviço da Web. Explicaremos mais sobre os diferentes métodos na seção a seguir.

Métodos

Nosso característica de serviço da Web permite que você escolha entre uma série de métodos para solicitar informações do URL especificado.

Se você estiver usando nossas chamadas API, a documentação informará qual método usar, conforme indicado na captura de tela abaixo.

Adição de credenciais a um serviço da Web

Como etapa opcional, é possível adicionar credenciais de autorização ao serviço da Web do fluxo da pesquisa do questionário. Os serviços da Web Fluxo da pesquisa são compatíveis com métodos básicos, de chave API e OAuth 2.0, e podem compartilhar credenciais com serviços da Web em fluxos de trabalho.

Definição de credenciais

1. Clique em Selecionar credenciais.
   
2. Você pode escolher entre um conjunto de credenciais existentes ou clicar em Adicionar uma conta de usuário.
   
   Qdica: as contas que você vê nessa janela podem incluir aquelas criadas para serviços da Web em fluxos de trabalho ou criadas por administradores Marca para uso por toda a organização.
3. Dê um nome para identificar suas credenciais posteriormente.
   
4. Selecione o tipo de conexão:
   • Básico: Forneça um nome de usuário e uma senha.
   • Chave API: Use um identificador exclusivo para se autenticar em uma API.
   • OAuth: Autorize o acesso de terceiros aos recursos do seu servidor sem compartilhar suas credenciais.
5. Configure a credencial escolhida seguindo as etapas desta página com link.
6. Decida se deseja usar o mTLS. Saiba mais na página do link.
   
7. Clique em Conectar conta.
8. Clique em Seguinte.
   
9. Suas credenciais aparecerão em seu serviço da Web.
   

Configuração de parâmetros de credenciais

Você pode ajustar onde suas credenciais são adicionadas na solicitação, além dos parâmetros de nome e modelo.

1. Clique nos três pontos avançar das credenciais.
   
2. Selecione Configurar parâmetros de credenciais.
3. Em Formato do parâmetro, escolha onde na solicitação as credenciais devem ser passadas:
   
   • Cabeçalho
   • Consulta
   • Corpo
4. Dê o nome do parâmetro.
5. Digite o modelo de parâmetro.
6. Clique em Salvar.

Substituição e remoção de credenciais

Clique nos três pontos avançar de suas credenciais para ver as seguintes opções:

• Configurar parâmetros de credenciais: Descrito acima.
• Substituir: Escolha ou adicione um conjunto diferente de credenciais salvas ao serviço da Web.
• Remover: Excluir as credenciais do serviço da Web. É assim que você mudaria o serviço da Web de autorizado para não autorizado.

Gerenciamento de contas

Na janela de credenciais, você pode gerenciar contas (credenciais individuais) clicando nos três pontos. Suas opções incluem:

• Renomear conta
• Gerenciar acesso
• Remover conta
• Editar conta (alterar como as credenciais são configuradas, como o tipo de autorização)

Algumas opções podem não estar disponíveis. Por exemplo, se você não criou uma conta, talvez não consiga excluí-la. Se você não for um administrador Marca, não poderá gerenciar o acesso do usuário às contas.

Gerenciamento de credenciais como administrador

Os administradores Marca podem criar credenciais de serviço da Web e controlar quais usuários da organização têm permissão para usá-las.

Para saber mais, consulte Administração extensões. A extensão é chamada WebService, sem espaços.

Parâmetros

Atualmente, há três tipos de parâmetros que você pode anexar à sua solicitação.

1. Parâmetro de consulta: Em vez de adicionar uma query string ao final do URL do serviço da Web, coloque os parâmetros de consulta aqui.
2. Parâmetro do corpo: Esse parâmetro não está disponível para solicitações GET ou DELETE. Ele vem com duas opções de formatação:
   • application/x-www-form-urlencoded: Em vez de inserir os parâmetros do corpo na área especificada do serviço Web, adicione-os como uma query string no final do URL especificado.
   • application/json: Insira cada um dos parâmetros do corpo da solicitação, certificando-se de especificar o tipo e o valor. Para parâmetros aninhados, como matrizes e objetos, você pode inserir suas chaves usando a notação de pontos ou inserir os valores diretamente como JSON bruto:
     • Essa imagem mostra os parâmetros do corpo usando a notação de pontos.
     • Esta imagem mostra os mesmos parâmetros do corpo, mas como JSON bruto.
       Atenção: Cada chave e valor em um objeto JSON, bem como cada elemento em uma matriz JSON (incluindo texto transportado), deve ter aspas duplas ao redor.
3. Cabeçalho personalizado: Insira os cabeçalhos de URL aqui.
   Qdica: os URLs de autenticação devem ser adicionados ao cabeçalho personalizado.

Se estiver usando nossas chamadas API, a documentação informará quais tipos de parâmetros devem ser incluídos. O exemplo abaixo fornece os parâmetros do corpo a serem definidos.

Adição de parâmetros ao serviço da Web

1. Selecione qualquer uma das 3 opções Adicionar um parâmetro para enviar ao serviço da Web indicadas na seção anterior. No exemplo acima, estamos indicando os parâmetros da consulta.
2. Digite o nome do parâmetro na caixa Parâmetro para serviço da Web à esquerda.
3. Digite o valor correspondente do parâmetro na caixa Value (Valor ) à direita.
4. Clique no sinal de mais(+) à direita do parâmetro para adicionar outro.
5. Clique em Aplicar quando terminar.

Teste de seus parâmetros

Depois de colar o URL e configurar os parâmetros, você pode testar o URL para ver quais campos podem ser extraídos.

1. Clique em Testar URL para ver quais informações você pode extrair do Web Service externo.
   
2. Selecione os campos que deseja usar ou registrar no seu pesquisa. O nome do campo aparece à esquerda e um valor de exemplo correspondente aparece à direita.
   
3. Clique em Add Embedded Data (Adicionar dados incorporados ) para adicionar campos selecionados aos seus dados.
   Qdica: o conjunto Dados integrados em um serviço da Web é registrado como um tipo de variável“conjunto de texto“.
   Qdica: Você pode alterar os nomes dados integrados associados aos campos do seu serviço da Web na coluna Definir dados incorporados. Os nomes dados integrados estão à esquerda do sinal de igual(=), indicado por um ícone de ED verde. O lado direito não deve ser alterado. Os nomes que você definir à esquerda serão os nomes dos campos conforme aparecem em seus dados.
4. Se você selecionar Fire and Forget, não salvará nenhum dos dados retornados da chamada do serviço da Web. Esse característica é útil quando você não precisa salvar os dados retornados.
   
   Qdica: Fire and Forget permite que seu pesquisa faça uma solicitação a um serviço da Web sem esperar por uma resposta. Isso significa que seus respondentes poderão concluir o pesquisa completo sem nenhum atraso devido ao serviço da Web. Talvez você queira usar essa opção se tiver uma solicitação de serviço da Web que demore um pouco para ser processada, mas recomendamos que você use esse característica somente durante os testes, pois ele impedirá que dados integrados sejam salvos.
5. Quando terminar, clique em Aplicar.

Correção de erros de TLS

A partir de 1º de setembro de 2021, as solicitações de serviços da Web com erros de segurança da camada de transporte (TLS) falharão. O TLS é o que torna as solicitações da Web por HTTPS (em oposição ao HTTP simples) seguras, impedindo que os dados da solicitação fiquem visíveis para terceiros e garantindo que a solicitação seja enviada para o destino correto. Ignorar erros de TLS efetivamente elimina esses benefícios de segurança; essa mudança é um passo importante em nossos esforços contínuos para melhorar a segurança da plataforma Qualtrics.

Para resolver cada erro de TLS, você precisa executar uma das seguintes ações:

• Corrija o erro de TLS. Devido à natureza dos erros de TLS, nossa equipe de suporte não pode fornecer orientações específicas sobre como fazer isso, mas o administrador da rede saberá como corrigir o erro.
• Altere a solicitação de serviço da Web do elemento de fluxo para que seja feita por HTTP e não por HTTPS. Por exemplo, você pode alterar o URL “https://example.com” para “http://example.com”. Se optar por essa abordagem, você também deve garantir que o URL HTTP não seja redirecionado para o URL HTTPS.
  Atenção: Observe que essa abordagem fará com que os dados da solicitação do serviço da Web sejam transmitidos sem criptografia.

Você pode verificar se o elemento de serviço da Web está pronto para essa alteração usando o botão de teste avançar do campo URL no elemento de fluxo. A visualização dos dados brutos na janela resultante, também mostrada abaixo, não deve mostrar nenhum erro.

Tipos de Projetos em que esse Característica está disponível

Desde que tenha acesso aos serviços da Web como parte de sua licença, você pode adicionar um serviço da Web a qualquer tipo de fluxo da pesquisa do projeto. Isso inclui:

• Projetos de pesquisa
• Engajamento
• 360
• Ciclo de vida
• Pesquisa pontual com funcionários
• Pesquisa de satisfação
• Soluções XM
• Conjuntos
• MaxDiff