Attività Servizio web

Informazioni sull’attività Servizio Web

L’attività Servizio Web è utile se hai esperienza con l’API e desideri attivare diversi flussi di lavoro all’interno del software Qualtrics, o a un servizio web esterno, quando il partecipante termina il sondaggio. Ad esempio, se il sondaggio raccoglie le informazioni di contatto del rispondente, un’attività del servizio Web può utilizzare la chiamata API di creazione contatto per aggiungere il rispondente a un elenco di contatti.

Si consiglia inoltre di visitare queste pagine relative ai servizi Web per maggiore assistenza e background:

• Hub sviluppatori Qualtrics
• Metodi Web Service
• Documentazione API
• Passaggio di informazioni tramite stringhe di query
• Testo trasferito

Configurazione di un’attività Servizio Web

A seconda di come si preferisce formattare i parametri del corpo, la configurazione sarà leggermente diversa. Se si utilizza il formato JSON o XML, inserire il corpo nella sezione Corpo. Se si preferisce codificare URL, è possibile aggiungere parametri come stringa di query al campo URL.

1. Creare un flusso di lavoro (o selezionarne uno esistente) nel proprio progetto o nella pagina Flussi di lavoro indipendenti.
   
2. Assicurarsi di trovarsi nella sezione Flussi di lavoro.
3. Fare clic su Crea un workflow.
4. Determinare la pianificazione o l’evento che avvia il task. (Vedere un confronto).
5. Fare clic su Aggiungere attività e selezionare WebService.
   
6. Scegliere il metodo di autenticazione. Le opzioni includono:
   
   • Autenticato: esegui una richiesta di servizio Web autenticata. Le opzioni di autenticazione includono le opzioni di base (con password e nome utente), chiave API e OAuth.
   • Non autenticato: esegui una richiesta di servizio Web senza autenticazione.
7. Fare clic su Successivo.
8. Se è stata selezionata una richiesta autenticata, selezionare le credenziali di autorizzazione dall’elenco oppure fare clic su Aggiungi account utente per aggiungere nuove credenziali. Per ulteriori informazioni, vedere Aggiunta di credenziali di autorizzazione.
   
   Qtip: potrai selezionare tutte le credenziali che hai aggiunto in precedenza, o quelle aggiunte da un Amministratore della licenza nella scheda Estensioni.
9. Fare clic su Successivo.
10. Se hai una richiesta formattata, puoi importarla per impostare automaticamente il tuo servizio web. Consultare la sezione Utilizzo dei comandi Curl per i dettagli.
    
11. Se lo si desidera, aggiungere un Riepilogo attività nella parte superiore dell’attività. Questa è una descrizione che spiega l’obiettivo dell’attività.
12. Scegliere il metodo di richiesta del servizio Web. Per ulteriori informazioni su ciascun metodo, consultare Metodi Web Service.
    
    Qtip: se stai utilizzando l’API Qualtrics, la documentazione ti indicherà che tipo di richiesta utilizzare.
    Attenzione: le attività WebService non consentono alcun reindirizzamento URL per richieste non GET. Per le richieste GET è consentito un solo reindirizzamento.
13. Immettere l’URL della richiesta.
    Qtip: è possibile limitare i domini a cui il task del servizio Web può connettersi specificando i domini nelle impostazioni dei domini di estensione.
14. Se lo si desidera, fare clic su Aggiungi intestazione per aggiungere un’intestazione. Specificare la Chiave e il Valore. Per rimuovere un’intestazione, fare clic sull’icona del cestino accanto all’intestazione.
    Consiglio Q: utilizza l’icona del testo trasferito, {a}, per inserire il testo trasferito per rilevare i valori dalle risposte al sondaggio o dalle attività precedenti nel flusso di lavoro.
    Attenzione: se utilizzi l’API Qualtrics, devi includere il token API attraverso l’intestazione. Per ulteriori informazioni, vedere Aggiunta di un’intestazione per le richieste API Qualtrics.
    Attenzione: per le richieste POST, PUT e PATCH è necessario specificare un tipo di dati per ogni coppia chiave-valore.
    Attenzione: i task del servizio Web attualmente non supportano commenti/testo nel corpo che contiene sequenze di escape.
15. Se hai scelto post, put o patch, dovrai scegliere il formato del tuo corpo. Le opzioni includono JSON, codifica URL, XML e Solo testo.
    
    
    Qtip: testo normale può essere specificato solo come testo libero. Quando si utilizza l’opzione Testo libero JSON, gli input non vengono salvati. Ciò significa che, ad esempio, un’immissione di testo trasferito contenente virgolette doppie o caratteri di nuova riga (ad esempio: \n) renderà il corpo JSON non valido e non verrà eseguito correttamente. Un’alternativa a questo è utilizzare l’opzione coppie chiave-valore o utilizzare un‘attività di codice per pulire o eseguire l’escape del testo da immettere nell’attività del servizio Web.
16. Determinare come si intende specificare il corpo della richiesta. È possibile aggiungere il corpo come coppie chiave-valore o testo libero.
17. Se sono state selezionate coppie chiave-valore, aggiungere la Chiave e il Valore associato. Fare clic su Aggiungi coppia chiave-valore per aggiungere ulteriori parametri.
18. Selezionare un Tipo di dati.
    • Booleano: selezionare questo tipo di dati se i dati hanno uno dei due valori possibili.
    • JSON: seleziona questo tipo di dati se i tuoi dati sono in formato JSON.
    • Numero: selezionare questo tipo di dati se i dati sono numerici.
    • Stringa: selezionare questo tipo di dati se i dati sono in formato testo.
    • Default di sistema: selezionare questo tipo di dati se si intende utilizzare il tipo di dati nativo per i propri dati. Se non è possibile trovare un tipo di dati, per impostazione predefinita verrà utilizzato il tipo Stringa.
      Qtip: si consiglia di selezionare uno degli altri tipi di dati per assicurarsi che il cast dei dati sia corretto.
      Attenzione: le coppie chiave-valore configurate prima del 16 settembre 2022 avranno un tipo di dati Default di sistema.
    Qtip: il campo Tipo di dati è disponibile solo quando si selezionano coppie JSON e Valore chiave nelle fasi 13-14.
19. Selezionare cosa accade se non è possibile eseguire il cast del tipo di dati.
    • Non eseguire il cast di un tipo di dati e contrassegnarlo come errore: se non è possibile eseguire il cast del tipo di dati, non verrà eseguito il cast di alcun tipo di dati e il task non riuscirà. Questo può essere visualizzato nella scheda Cronologia esecuzione.
    • Crea il tipo di dati allo standard di sistema: se non è possibile eseguire il cast del tipo di dati, il tipo di dati verrà impostato su Default di sistema.
20. Se è stato selezionato Testo libero, immettere i parametri del corpo nel formato selezionato.
    
    Attenzione: questo campo non deve essere lasciato vuoto o avere chiavi senza valori. Invece, non includere affatto il campo o immettere il termine “null” per indicare valori vuoti. Si consiglia di escludere il campo.
21. Per verificare il servizio Web, fare clic su Esegui test.
    
    Consiglio Q: Dopo aver fatto clic su Esegui test, apparirà il risultato della tua richiesta, per farti sapere se è andata a buon fine o meno, e il JSON o XML risultante, se è andata a buon fine.
22. Fare clic su Aggiungi percorso personalizzato per aggiungere percorsi JSON o XML. Questi percorsi consentono di utilizzare i risultati del servizio Web in testo trasferito, da utilizzare con altre attività del flusso di lavoro, ad esempio un‘attività di codice. Se hai testato il tuo servizio web, potresti avere valori automaticamente qui, in quanto Qualtrics li tirerà fuori automaticamente dai risultati.
    Qtip: fai clic su Aggiungi percorso personalizzato per aggiungere percorsi supplementari o fai clic sul cestino accanto a un percorso per eliminarlo.
23. Al termine della configurazione del workflow, fare clic su Salva.

Aggiunta di credenziali di autorizzazione

Questa sezione descrive come aggiungere credenziali di autorizzazione per l’attività del servizio Web. È possibile aggiungere credenziali utilizzando il metodo Base, Chiave API o OAuth 2.0. Per aggiungere credenziali, fare clic su Aggiungi account utente dalla finestra di selezione delle credenziali.

Base

L’autenticazione standard richiede il login con il nome utente e la password dell’account.

1. Assegnare un Nome alle proprie credenziali. Questo è solo per scopi organizzativi dell’utente.
2. Selezionare Base come tipo di connessione.
3. Immettere il Nome utente richiesto per l’autenticazione.
4. Immettere la Password per l’autenticazione.
5. Fare clic su Connetti account.

Chiave API

L’autenticazione chiave API consente di eseguire l’autenticazione utilizzando un token API statico.

1. Assegnare un Nome all’account. Questo è solo per scopi organizzativi dell’utente.
2. Selezionare Chiave API come tipo di connessione.
3. Immettere il Token API utilizzato per l’autenticazione.
4. Fare clic su Connetti account.

OAuth 2.0

L’autorizzazione OAuth2.0 elimina la necessità di utilizzare token API statici o nome utente e password di base per l’integrazione con piattaforme di terze parti. L’attività del servizio Web supporta due diversi tipi di autorizzazione OAuth2.0: codice di autorizzazione e credenziali client.

È possibile utilizzare l’autorizzazione OAuth 2.0 per integrarsi senza soluzione di continuità con molte piattaforme di terze parti. L’implementazione del servizio Web Qualtrics segue la specifica OAuth ufficiale. Tuttavia, alcuni sistemi esterni potrebbero avere configurazioni leggermente diverse che portano a incompatibilità con l’autorizzazione OAuth2.0 nell’attività del servizio Web.

Le seguenti integrazioni sono alcuni esempi che sono stati completamente verificati per l’utilizzo di OAuth2.0:

• Salesforce utilizza il metodo del codice di autorizzazione.
• Jira utilizzando il metodo del codice di autorizzazione.
• Eseguire lo zoom utilizzando il metodo del codice di autorizzazione.

Per eseguire l’autenticazione utilizzando OAuth 2.0:

1. Assegnare un Nome all’account. Questo è solo per scopi organizzativi propri.
2. Selezionare OAuth come tipo di connessione.
3. Selezionare il tipo di concessione o la modalità di recupero del token di accesso. È possibile scegliere:
   • Codice di autorizzazione
   • Credenziali del client
4. Immettere l’ ID client e la Chiave client segreta.
5. Immettere l’ Endpoint token.
6. Se è stato selezionato il codice di autorizzazione come tipo di concessione, immettere il punto di accesso Autorizzazione.
7. Fare clic su Connetti account.

Ridenominazione e rimozione delle credenziali

Per modificare il nome della tua credenziale, fai clic sui tre puntini accanto all’account. Per rimuovere le credenziali, fare clic su Rimuovi account.

Aggiunta di un’intestazione per le richieste API Qualtrics

Quando utilizzi l’API Qualtrics, devi includere il tuo token API come intestazione nel tuo servizio web.

1. Configurare l’attività del servizio Web, selezionare le credenziali e scegliere la richiesta.
   
2. Nella sezione Intestazioni, inserire X-API-TOKEN come Chiave.
3. Per il valore, fare clic sull’icona di testo trasferito, {a}.
4. Selezionare le credenziali dall’elenco.
   

TLS reciproca

La sicurezza del livello di trasporto reciproco (mTLS) è un ulteriore livello facoltativo di sicurezza oltre ai meccanismi di autenticazione API standard (come token API o OAuth). La autenticazione TLS reciproca garantisce che sia la persona che si connette a un’API/servizio Web sia l’API/il servizio Web stesso abbiano un traffico crittografato sicuro in entrambe le direzioni. Una volta abilitato mTLS, affinché le richieste abbiano esito positivo tutte le richieste devono presentare il certificato client corretto. Se un chiamante effettua una richiesta utilizzando un certificato client non valido o mancante, l’API che sta tentando di chiamare bloccherà la richiesta.

Requisiti

Ogni servizio varia a seconda che supporti mTLS e in quale formato fornisca informazioni chiave. È garantito solo il supporto di mTLS per i servizi che soddisfano i nostri requisiti:

• Fornire una chiave privata
• La chiave privata può essere formattata in PKCS8
• Fornisci un certificato
• Il certificato può essere formattato in X.509

Le API pubbliche di Qualtrics supportano mTLS come descritto sopra.

mTLS è supportato solo per i servizi Web autenticati creati nei flussi di lavoro. Sono supportati tutti e tre i metodi di autenticazione (Base, Chiave API e OAuth2.0).

Aggiunta di mTLS

1. Creare l’attività del servizio Web.
   
2. Selezionare Autenticato.
   
3. Fare clic su Successivo.
4. Aggiungere un account utente.
   
   Qtip: un Amministratore della licenza può connettersi a un account utilizzando la pagina Estensioni.
   
5. Selezionare un tipo di connessione e immettere le credenziali.
   
6. Selezionare Abilita mTLS.
7. La chiave privata può essere pensata come l’identificatore univoco del client che tenta di connettersi. Questo valore deve essere in formato PKCS8.
   Qtip: se la chiave è in un formato diverso, è possibile modificare l’utilizzo di un altro programma per modificare questo formato.
   Qtip: se intendi utilizzare l’API Qualtrics con il tuo servizio web, consulta la nostra Documentazione API su mTLS. In questa documentazione verrà illustrato come estrarre la chiave privata. Quando incolla il valore in Qualtrics, dovrai includere trattini che indicano “start private key” e “end private key”.
8. La chiave pubblica è il certificato mTLS. Questo valore deve essere in formato X.509.
   Qtip: se intendi utilizzare l’API Qualtrics con il tuo servizio web, consulta la nostra Documentazione API su mTLS. In questa documentazione verrà illustrato come estrarre il certificato. Quando incolla il valore in Qualtrics, dovrai includere trattini come “inizio certificato” e “fine certificato”.
9. Al termine, fai clic su Connetti account.
10. Procedere con la configurazione del servizio Web.

Utilizzo dei comandi Curl

I comandi Curl sono uno dei tanti modi in cui è possibile effettuare richieste HTTP, e sono uno strumento prezioso per trasmettere informazioni avanti e indietro attraverso gli URL. È possibile importare un comando curl mentre si sta impostando il task per popolare automaticamente diverse configurazioni del servizio Web.

Molti documenti API spesso forniscono esempi di curl che è possibile utilizzare. Essere in grado di copiare e importare questi comandi può così rendere la configurazione del servizio web molto più veloce e più facile.

Per alcuni esempi di richieste curl, guardare a destra in ciascuno di questi documenti API:

• Ottieni lista di invio
• Crea distribuzione promemoria
• Aggiornare transazione contatto
• Elenca utenti nel gruppo

Per una richiesta GET, il comando curl può essere semplice come curl https://api.example.com/parameters. Per i comandi curl che non sono così semplici, forniremo alcuni parametri comuni.

Parametri di comando Curl supportati

Di seguito sono riportati alcuni dei parametri curl supportati dall’attività del servizio web Qualtrics:

Parametri testata comuni

Sopra, abbiamo menzionato che è possibile utilizzare i comandi curl per definire le intestazioni. Le testate servono a vari scopi nella comunicazione HTTP, come ad esempio fornire informazioni sulla richiesta e controllare l’autenticazione. Le testate specifiche utilizzate dipendono dai requisiti dell’applicazione o dell’API in uso.

Di seguito sono riportati alcuni esempi di parametri testata:

Parametri non supportati

I parametri curl non elencati sopra non sono supportati. Ecco alcuni esempi di formati di comandi curl Le attività del servizio web Qualtrics non supportano:

• --cookie per inviare cookie con la richiesta.
• --L o --location per i seguenti reindirizzamenti.
• --max-time per impostare il tempo massimo di richiesta.
• --o--output per salvare la risposta a un file.
• --insicuro per consentire connessioni non sicure.
• --A o --user-agent per specificare l’agente utente.

Importazione dei comandi Curl

1. Durante la configurazione dell’attività del servizio Web, fare clic su Importa cURL.
   
2. Incollare il comando curl nella casella.
   
   Attenzione: Assicurati di includere il tuo metodo HTTP nella tua richiesta curl, specialmente se stai copiando un comando curl da un’altra piattaforma.
   Consiglio Q: Tieni d’occhio parti della richiesta che devi compilare con le tue informazioni. Ad esempio, nello screenshot precedente, sostituiresti “Chiave API” con il tuo token API.

   Consiglio Q: è possibile aggiungere un comando in una singola stringa o contrassegnare le interruzioni di riga utilizzando il carattere di escape ( \ ). Non supportiamo altre fughe di linea (ad esempio, ^ ). Di seguito è riportato un esempio di comando curl con caratteri di escape supportati:

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

3. Fai clic su Importa.
4. I campi del servizio Web verranno alimentati automaticamente.

FAQ