Modello di articolo

Informazioni sull’attività del servizio web

L’attività Servizio web è utile se si ha esperienza con le API e si desidera attivare diversi flussi di lavoro all’interno del software Qualtrics, o verso un servizio web esterno, quando il rispondente 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 create contact per aggiungere il rispondente a un elenco di contatti.

Si consiglia inoltre di visitare queste pagine relative al servizio web per ulteriori informazioni e approfondimenti:

• Hub per gli sviluppatori di Qualtrics
• Metodi dei servizi web
• Documentazione API
• Passaggio di informazioni tramite stringa query
• Testo trasferito

Impostazione di un’attività di servizio web

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

1. Creare un flusso di lavoro (o selezionarne uno esistente) nel progetto o nella pagina Flussi di lavoro indipendente.
   
2. Assicuratevi di essere nella sezione Flussi di lavoro.
3. Fare clic su Crea un flusso di lavoro.
4. Determinare l’orario o l’evento che fa scattare l’attività.(Vedere un confronto)
5. Fare clic su Aggiungi attività e selezionare WebService.
   
6. Scegliere il metodo di autenticazione. Le opzioni comprendono:
   
   • Autenticatore: Esegue una richiesta di servizio Web autenticata. Le opzioni di autenticatore sono: base (con password e nome utente), chiave API e OAuth.
   • Non autenticato: Esegue una richiesta di servizio Web senza autenticazione.
7. Fare clic su Successivo.
8. Se si è selezionata una richiesta autenticata, selezionare le credenziali di autorizzazione dalla lista o fare clic su Aggiungi account utente per aggiungere nuove credenziali. Per ulteriori informazioni, vedere Aggiunta di credenziali di autorità.
   
   Consiglio Q: nella scheda Estensioni è possibile selezionare le credenziali aggiunte in precedenza o quelle aggiunte da un Brand Administrator.
9. Fare clic su AVANTI.
10. Se si dispone di una richiesta formattata in curl, è possibile importarla per impostare automaticamente il servizio web. Per maggiori dettagli, vedere la sezione Uso dei comandi Curl.
    
11. Se si desidera, aggiungere un riepilogo dell’attività nella parte superiore dell’attività. Si tratta di una descrizione che spiega l’obiettivo dell’attività.
12. Scegliere il metodo Request del servizio web. Per ulteriori informazioni su ciascun metodo, vedere Metodi dei servizi Web.
    
    Consiglio Q: se si utilizza l’API di Qualtrics, la documentazione indica il tipo di richiesta da utilizzare.
    Attenzione: Le attività di WebService non consentono alcun reindirizzamento dell’URL per le richieste non GET. È consentito un solo reindirizzamento per le richieste GET.
13. Inserire l’URL della richiesta.
    Consiglio Q: È possibile limitare i domini a cui l’attività del servizio Web può connettersi specificando i domini nelle impostazioni dei domini di estensione.
14. Se 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 avanti all’intestazione.
    Consiglio Q: Usare l’icona del testo trasferito, {a}, per inserire il testo trasferito per estrarre i valori dalle risposte del sondaggio o da attività precedenti nel flusso di lavoro.
    Attenzione: Se si utilizza l’API di Qualtrics, è necessario includere il token API nell’intestazione. Per ulteriori informazioni, vedere Aggiunta di un’intestazione per le richieste API di QUALTRrics.
15. Se avete scelto post, put o patch, dovrete scegliere il formato del corpo. Le opzioni includono JSON, URL-Encoded, XML e Testo normale.
    
    
16. Stabilire come specificare il corpo della richiesta. È possibile aggiungere il corpo come coppie chiave-valore o testo libero.
17. Se si sono selezionate le coppie chiave-valore, aggiungere la chiave e il valore associato. Fare clic su Aggiungi coppia chiave-valore per aggiungere altri parametri.
    Attenzione: Per le richieste POST, PUT e PATCH è necessario specificare un tipo di dati per ogni coppia chiave-valore.
18. Selezionare un tipo di dati.
    • Booleano: Selezionare questo tipo di dati se i dati hanno uno dei due valori possibili.
    • JSON: selezionare questo tipo di dati se i 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.
    • Predefinito dal sistema: Selezionare questo tipo di dati se si desidera utilizzare il tipo di dati nativo per i dati. Se non è possibile trovare un tipo di dati, il valore predefinito è String.
      Consiglio Q: si consiglia di selezionare uno degli altri tipi di dati per assicurarsi che i dati vengano lanciati correttamente.
      Attenzione: Le coppie chiave-valore configurate prima del 16 settembre 2022 avranno un tipo di dati System Default.
    Consiglio Q: il campo Tipo di campo è disponibile solo quando si selezionano JSON e Coppie chiave-valore nei passaggi 13-14.
19. Selezionare cosa succede se il tipo di dati non può essere lanciato.
    • Non eseguire il cast di un tipo di dati e segnalarlo come errore: Se il tipo di dati non può essere lanciato, non verrà lanciato alcun tipo di dati e l’attività fallirà. Questo è visibile nella scheda Cronologia sessioni.
    • Se il tipo di dati non può essere convertito, il tipo di dati verrà impostato su System Default.
20. Se si è selezionato Testo libero, inserire i parametri del corpo nel formato selezionato.
    
    Attenzione: Non si deve lasciare questo campo vuoto o avere chiavi senza valori. Invece, non includere affatto il campo o inserire il termine “null” per indicare valori vuoti. Si consiglia di escludere il campo.
    Consiglio Q: se un’attività del servizio Web incontra un corpo JSON non valido, l’attività non fallirà. Invece, il JSON non valido sarà convertito in una stringa e salvato come proprietà “text” in un nuovo oggetto JSON. In questo modo, sarà possibile vedere il testo non valido una volta che l’attività ha terminato l’elaborazione.
    Attenzione: Le attività del servizio Web non supportano attualmente i commenti.
21. Per testare il servizio Web, fare clic su Esegui test.
    
    Consiglio Q: dopo aver fatto clic su Esegui test, apparirà il risultato della richiesta, con l’indicazione del successo o meno della stessa e del JSON o XML risultante, in caso di successo.
22. Fare clic su Aggiungi percorso personalizzato per aggiungere percorsi JSON o XML. Questi percorsi consentono di utilizzare i risultati del servizio Web in un testo trasferito, da utilizzare con altre attività del flusso di lavoro, ad esempio un’attività di codifica. Se avete testato il vostro servizio web, potreste avere automaticamente dei valori in questo punto, poiché Qualtrics li estrarrà automaticamente dai risultati.
    Consiglio Q: fare clic su Aggiungi percorso personalizzato per aggiungere altri percorsi o fare clic sul cestino accanto a un percorso per eliminarlo.
23. Una volta terminata l’impostazione del flusso di lavoro, fare clic su Salva.

Aggiunta delle credenziali di autorità

Questa sezione spiega come aggiungere le credenziali di autorizzazione per l’attività del servizio Web. È possibile aggiungere le credenziali utilizzando i metodi Basic, API Key o OAuth 2.0. Per aggiungere le credenziali, fare clic su Aggiungi account utente nella finestra di selezione delle credenziali.

Base

L’autenticazione di base richiede l’accesso con il nome utente e la password del proprio account.

1. Date un nome alle vostre credenziali. Questo è solo per scopi organizzativi.
2. Scegliere Basic come tipo di connessione.
3. Inserire il nome utente richiesto per l’autenticatore.
4. Inserire la password per l’autenticatore.
5. Fare clic su Connetti account.

Chiave API

L’autenticazione con chiave API consente di autenticarsi utilizzando un token API statico.

1. Assegnare un nome all’account. Questo è solo per scopi organizzativi.
2. Scegliere la chiave API come tipo di connessione.
3. Inserire il Token API utilizzato per l’autenticazione.
4. Fare clic su Connetti account.

OAuth 2.0

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

È possibile utilizzare l’autorità OAuth 2.0 per integrarsi perfettamente con molte piattaforme di terze parti. L’implementazione del servizio web di Qualtrics segue le specifiche ufficiali di OAuth. Tuttavia, alcuni sistemi esterni possono avere configurazioni leggermente diverse che comportano incompatibilità con l’autorizzazione OAuth2.0 nell’attività del servizio web.

Le seguenti integrazioni sono alcuni esempi che sono stati pienamente verificati per funzionare con OAuth2.0:

• Salesforce utilizzando il metodo del codice di autorizzazione.
• Jira utilizzando il metodo del codice di autorizzazione.
• Zoom con il metodo del codice di autorizzazione.

Per autenticarsi usando OAuth 2.0:

1. Assegnare un nome all’account. Questo è solo a scopo organizzativo.
2. Scegliere OAuth come tipo di connessione.
3. Scegliere il tipo di concessione, ovvero il modo in cui viene recuperato il token di accesso. Si può scegliere:
   • Codice di autorizzazione
   • Credenziali del client
4. Immettere l’ID e il segreto delclient.
5. Inserire l’endpoint del token.
6. Se si è selezionato il codice di autorizzazione come tipo di sovvenzione, inserire l’endpoint Autorizzazione.
7. Fare clic su Connetti account.

Rinominare & rimuovere le credenziali

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

Aggiunta di un’intestazione per le richieste API di Qualtrics

Quando si utilizza l’API di Qualtrics, è necessario includere il token API come intestazione nel servizio web.

1. Impostare l’attività del servizio web, selezionare le credenziali e scegliere la richiesta.
   
2. Nella sezione Intestazioni, inserire X-API-TOKEN API come chiave.
3. Per il valore, fare clic sull’icona del testo trasferito, {a}.
4. Selezionare le credenziali dalla lista.
   

TLS reciproco

La sicurezza reciproca del livello di trasporto (mTLS) è un livello di sicurezza aggiuntivo e opzionale che si aggiunge ai meccanismi di autenticazione API standard (come Token API o OAuth). Il TLS reciproco garantisce che sia la persona che si connette a un’API/servizio web sia l’API/servizio web stesso abbiano un traffico sicuro e crittografato in entrambe le direzioni. Una volta abilitato l’mTLS, tutte le richieste devono presentare il certificato corretto del client per essere accettate. Se un chiamante effettua una richiesta utilizzando un certificato client non valido o mancante, l’API che sta cercando di chiamare bloccherà la richiesta.

Requisiti

Ogni servizio varia in base al supporto o meno di mTLS e al formato in cui fornisce le informazioni chiave. Il supporto di mTLS è garantito solo per i servizi che corrispondono ai nostri requisiti:

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

Le API pubbliche di Qualtrics supportano l’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 (Basic, API key e OAuth2.0).

Aggiunta di mTLS

1. Creare l’attività del servizio Web.
   
2. Scegliere Autenticatore.
   
3. Fare clic su Successivo.
4. Aggiungere un account utente.
   
   Consiglio: un Brand administrator può collegarsi a un account utilizzando la pagina delle estensioni.
   
5. Selezionare un tipo di connessione e compilare le credenziali.
   
6. Selezionare Abilita mTLS.
7. La chiave privata può essere considerata come l’identificatore univoco del client che cerca di connettersi. Questo valore deve essere in formato PKCS8.
   Consiglio Q: se la chiave è in un formato diverso, è possibile cambiare il formato con un altro programma.
   Consiglio q: se si intende utilizzare l’API di Qualtrics con il proprio servizio web, consultare la documentazione API su mTLS. Questa documentazione mostra come estrarre la chiave privata. Quando si incolla il valore in Qualtrics, è necessario includere i trattini “inizio chiave privata” e “fine chiave privata”
8. La chiave pubblica è il certificato mTLS. Questo valore deve essere in formato X.509.
   Consiglio q: se si intende utilizzare l’API di Qualtrics con il proprio servizio web, consultare la documentazione API su mTLS. Questa documentazione mostra come estrarre il certificato. Quando si incolla il valore in Qualtrics, è necessario includere i trattini che indicano “inizio certificato” e “fine certificato”
9. Al termine, fare clic su Connetti account.
10. Procedere con la configurazione del servizio web.

Utilizzo dei comandi Curl

I comandi Curl sono uno dei tanti modi per effettuare richieste HTTP e sono uno strumento prezioso per passare informazioni avanti e indietro attraverso gli URL. È possibile importare un comando curl durante l’impostazione dell’attività, per riempire automaticamente diverse configurazioni di servizi web.

Molti documenti delle API forniscono spesso esempi di curl che possono essere utilizzati. La possibilità di copiare e importare questi comandi può quindi rendere la configurazione dei servizi Web molto più rapida e semplice.

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

• Ottenere la LISTA DI INVIO
• Creazione di una distribuzione di promemoria
• Aggiornamento della transazione di contatto
• Lista degli 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 del comando Curl supportati

Ecco alcuni dei parametri curl supportati dal servizio web SUPPORTO QUALTRICS:

Parametri comuni dell’intestazione

Sopra abbiamo detto che si possono usare i comandi curl per definire le intestazioni. Le intestazioni hanno vari scopi nella comunicazione HTTP, come fornire informazioni sulla richiesta e controllare l’autenticità. Gli header specifici da utilizzare dipendono dai requisiti dell’applicazione o dell’API in uso.

Ecco alcuni esempi di parametri di intestazione:

Parametri non supportati

I parametri curl non elencati sopra non sono supportati. Ecco alcuni esempi di formati di comandi curl che i servizi web di Supporto Qualtrics non supportano:

• –-cookie per inviare i cookie con la richiesta.
• –-L o --location per i reindirizzamenti successivi.
• –-max-time per impostare il tempo massimo di richiesta.
• –-o o --output per salvare le risposte in un file.
• —Insecure per consentire connessioni non sicure.
• –-A o --user-agent per specificare l’agente utente.

Importare i comandi Curl

1. Durante l’impostazione dell’attività del servizio Web, fare clic su Importa cURL.
   
2. Incollare il comando curl nella casella.
   
   Attenzione: Assicurarsi di includere il metodo HTTP nella richiesta di curl, soprattutto se si sta copiando un comando curl da un’altra piattaforma.
   Consiglio Q: fate attenzione alle parti della richiesta che dovete compilare con le vostre informazioni. Ad esempio, nella schermata precedente, si sostituisce “API Key” con il proprio token API.

   Consiglio Q: È possibile aggiungere un comando in un’unica stringa, oppure marcare le interruzioni di riga usando il carattere di escape ( \ ). Non sono supportati altri escape di riga (ad esempio, ^ ). Ecco un esempio di comando curl con i caratteri di escape supportati:

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

3. Fai clic su Importa.
4. I campi del servizio web verranno compilati automaticamente.

FAQ