Attività Servizio web

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

Consiglio Q: Questa pagina contiene riferimenti all’API di Qualtrics, una funzione che richiede un’autorizzazione speciale per l’accessibilità. Se siete interessati a ottenere l’accessibilità a questa funzione, contattate il vostro BRAND ADMINISTRATOR per maggiori informazioni.

Attenzione: L’impostazione di un servizio Web richiede spesso conoscenze avanzate di programmazione. Sebbene il nostro team di assistenza sia lieto di aiutarvi con le nozioni di base per l’inserimento delle informazioni nel servizio web, non possiamo fornire assistenza sugli aspetti di programmazione.

Attenzione: Le attività del servizio Web supportano solo i seguenti tipi di contenuto: URL-Encoded, XML, JSON e Plain Text.

Consiglio Q: si sta impostando il servizio web da un documento API? La configurazione può essere molto più veloce se si importa un comando curl.

Impostazione di un’attività di servizio web

Attenzione: L’output della chiamata effettuata nell’attività del servizio Web ha un limite di 1 MB.

Consiglio Q: è possibile utilizzare l’Assistente AI per impostare l’attività del servizio web. Per ulteriori informazioni, vedere Utilizzo di AI Assist per l’impostazione delle attività.

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.

Creare un flusso di lavoro (o selezionarne uno esistente) nel progetto o nella pagina Flussi di lavoro indipendente.

---

×

close

Assicuratevi di essere nella sezione Flussi di lavoro.

Fare clic su Crea un flusso di lavoro.

Determinare l’orario o l’evento che fa scattare l’attività.(Vedere un confronto)

Fare clic su Aggiungi attività e selezionare WebService.

---

×

close

Scegliere il metodo di autenticazione. Le opzioni comprendono:

---

×

close

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

Fare clic su Successivo.

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

---

×

close

Consiglio Q: nella scheda Estensioni è possibile selezionare le credenziali aggiunte in precedenza o quelle aggiunte da un Brand Administrator.

Fare clic su AVANTI.

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.

---

×

close

Se si desidera, aggiungere un riepilogo dell’attività nella parte superiore dell’attività. Si tratta di una descrizione che spiega l’obiettivo dell’attività.

Scegliere il metodo Request del servizio web. Per ulteriori informazioni su ciascun metodo, vedere Metodi dei servizi Web.

---

×

close

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.

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.

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.

Se avete scelto post, put o patch, dovrete scegliere il formato del corpo. Le opzioni includono JSON, URL-Encoded, XML e Testo normale.

---

×

close

Stabilire come specificare il corpo della richiesta. È possibile aggiungere il corpo come coppie chiave-valore o testo libero.

Consiglio Q: il numero massimo di caratteri per le coppie chiave-valore e per il testo libero è di 75.000.

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.

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.

  

  Consiglio Q: assicurarsi che i dati inseriti siano JSON validi. Quando si utilizza un testo trasferito, assicurarsi che non siano inclusi caratteri speciali.

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

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.

Se si è selezionato Testo libero, inserire i parametri del corpo nel formato selezionato.

---

×

close

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.

Per testare il servizio Web, fare clic su Esegui test.

---

×

close

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.

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.

Attenzione: I dati di un’attività fallita non possono essere trasferiti in un’altra attività. Il testo trasferito verrà visualizzato come valore nullo.

Una volta terminata l’impostazione del flusso di lavoro, fare clic su Salva.

Consiglio Q: le attività del servizio Web hanno un timeout di 16 secondi. Se la chiamata al servizio Web richiede più di 10 secondi, il flusso di lavoro fallisce.

Utilizzo dell’assistente AI per l’impostazione delle attività

Attenzione: È possibile utilizzare la mappatura automatica solo se un Brand Administrator ha abilitato l’autorizzazione AI nella configurazione dei flussi di lavoro per l’organizzazione nella scheda Amministrazione.

L’Assistente AI può configurare l’integrazione API nelle attività di servizio web leggendo la documentazione API disponibile pubblicamente e impostando automaticamente l’attività.

Creare un flusso di lavoro con un’attività di servizio Web.

Scegliere il metodo di autenticazione. Per ulteriori informazioni, vedere Impostazione di un’attività di servizio Web.

Fare clic su Prova l’assistente AI.

---

×

close

Selezionare il servizio Web.

Descrivere l’intento o la richiesta della chiamata API.

Fare clic su Genera bozza.

Consiglio Q: se l’Assistente AI non è in grado di generare una bozza, modificare la richiesta e riprovare.

Valutare la configurazione delle API.

---

×

close

Per testare il servizio Web, fare clic su Esegui test.

---

×

close

Fare clic su Aggiungi percorso personalizzato per aggiungere percorsi JSON o XML. Per ulteriori informazioni, vedere Impostazione di un’attività di servizio Web.

Fai clic su Salva.

Consiglio q: Sebbene siano stati posti dei paletti e i nostri prodotti vengano continuamente perfezionati, l’intelligenza artificiale può talvolta generare risultati imprecisi, incompleti o non aggiornati. Prima di utilizzare qualsiasi output delle funzioni di IA di Qualtrics, è necessario rivedere l’output per verificarne l’accuratezza e assicurarsi che sia adatto al proprio caso di utilizzo. L’output delle funzioni di IA di Qualtrics non sostituisce la revisione umana o una guida professionale.

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.

Consiglio Q: tutti i tipi di connessione sono compatibili con mTLS. Per saperne di più, consultare la sezione Mutual TLS.

Base

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

---

×

close

Chiave API

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

---

×

close

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.

Consiglio Q: quando si crea una connessione OAuth, l’URL di reindirizzamento sarà https://{dataCenter}.qualtrics.com/oauth-client-service/redirect, dove {dataCenter} rappresenta il valore associato al proprio account. Per maggiori dettagli sulla ricerca del datacenter del vostro account, consultate questa pagina.

Per autenticarsi usando OAuth 2.0:

---

×

close

Consiglio Q: per gli utenti che impostano le credenziali di Google OAuth, includere il seguente parametro alla fine dell’endpoint del token: “?prompt=consenso” Se si dispone di parametri di query esistenti, il punto interrogativo non è necessario.

Consiglio Q: se avete problemi di connessione con Snowflake, assicuratevi che gli intervalli IP di Qualtrics siano inseriti nell’elenco dei permessi.

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.

---

×

close

Consiglio Q: è possibile rinominare o rimuovere solo le credenziali aggiunte dall’utente stesso.

Attenzione: Fare attenzione quando si cancellano le credenziali! Tutti i flussi di lavoro che utilizzano le credenziali smetteranno di funzionare quando le credenziali vengono eliminate.

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.

Impostare l’attività del servizio web, selezionare le credenziali e scegliere la richiesta.

---

×

close

Nella sezione Intestazioni, inserire X-API-TOKEN API come chiave.

Per il valore, fare clic sull’icona del testo trasferito, {a}.

Selezionare le credenziali dalla lista.

---

×

close

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

Creare l’attività del servizio Web.

---

×

close

Scegliere Autenticatore.

---

×

close

Fare clic su Successivo.

Aggiungere un account utente.

---

×

close

Consiglio: un Brand administrator può collegarsi a un account utilizzando la pagina delle estensioni.

---

×

close

Selezionare un tipo di connessione e compilare le credenziali.

---

×

close

Selezionare Abilita mTLS.

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”

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”

Al termine, fare clic su Connetti account.

Procedere con la configurazione del servizio web.

Consiglio Q: la validità delle chiavi mTLS non può essere verificata fino a quando non si esegue una chiamata API attraverso il servizio web, quindi non verrà visualizzato un messaggio di errore in questa pagina se le chiavi sono state inserite in modo errato. Provate a testare il servizio web prima di rendere attivo il flusso di lavoro.

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.

Consiglio Q: se si modifica un’attività di servizio web esistente, qualsiasi comando curl importato sovrascriverà le configurazioni precedenti.

Consiglio Q: Se siete interessati a saperne di più su curl rispetto a quanto descritto di seguito, vi consigliamo di leggere una risorsa esterna al Supporto Qualtrics, come la documentazione di IBM.

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.

Consiglio Q: se si tenta di importare un comando curl con parametri non supportati, verrà visualizzato un messaggio di errore con la lista dei parametri non supportati utilizzati. Verrà data la possibilità di continuare a importare il comando curl con la rimozione dei parametri non supportati.

Importare i comandi Curl

Durante l’impostazione dell’attività del servizio Web, fare clic su Importa cURL.

---

×

close

Incollare il comando curl nella casella.

---

×

close

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

Fai clic su Importa.

I campi del servizio web verranno compilati automaticamente.

Consiglio Q: si consiglia di ricontrollare i campi prima di attivare il flusso di lavoro.