Passa al contenuto principale
Loading...
Skip to article
  • Qualtrics Platform
    Qualtrics Platform
  • Customer Journey Optimizer
    Customer Journey Optimizer
  • XM Discover
    XM Discover
  • Qualtrics Social Connect
    Qualtrics Social Connect

Attività Servizio web


Was this helpful?


This site is protected by reCAPTCHA and the Google Privacy Policy and Terms of Service apply.

The feedback you submit here is used only to help improve this page.

That’s great! Thank you for your feedback!

Thank you for your feedback!


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:

Qtip: questa pagina contiene riferimenti all’API di Qualtrics, una funzione che richiede un’autorizzazione speciale per l’accesso. Se sei interessato ad ottenere l’accesso a questa funzione, contatta il tuo Amministratore della licenza per ulteriori informazioni.
Attenzione: l’impostazione di un servizio web richiede spesso conoscenze avanzate di programmazione. Anche se il nostro team di supporto è lieto di contribuire con le nozioni di base per inserire le informazioni nel servizio web, non possiamo fornire supporto sugli aspetti programmatici.
Attenzione: i task del servizio Web supportano solo i seguenti tipi di contenuto: Codificato URL, XML, JSON e Testo normale.
Qtip: Stai configurando il tuo servizio Web da un documento API? La configurazione può essere molto più veloce se si importa un comando curl.

Configurazione di un’attività Servizio Web

Attenzione: l’output della chiamata effettuata nel task Web Service ha un limite di 1 MB.

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.
    Nella scheda dei flussi di lavoro, fare clic su Crea un flusso di lavoro, quindi su Avviato alla ricezione di un evento
  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.
    levento Web Service
  6. Scegliere il metodo di autenticazione. Le opzioni includono:
    scegliendo il tipo di autenticazione e facendo clic su Avanti

    • 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.
    aggiunta di un account utente o selezione di un account esistente

    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.
    Pulsante che dice di ottenere una stella principale importando comandi curl; campo di riepilogo attività
  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.
    selezionare la richiesta e inserire un URL

    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.
    aggiunta di parametri del corpo nel servizio Web, quindi aggiunta di una coppia chiave-valore alla richiesta del corpo

    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.
    Corpo impostato su testo libero, quindi al posto delle coppie di valori chiave è presente un campo di testo grande

    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.
    Esegui pulsante di prova. Sezione denominata testo trasferito in cui aggiungi percorsi JSON

    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.
Qtip: le attività del servizio Web hanno un timeout di 16 secondi. Se una chiamata al servizio Web richiede più di 10 secondi, il workflow non riuscirà.

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.

Qtip: tutti i tipi di connessione sono compatibili con mTLS. Per ulteriori informazioni, consultare la sezione TLS reciproca.

Base

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

aggiunta di un nuovo account di autenticazione di base

  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.

aggiunta di un nuovo account API

  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.
Qtip: quando si crea una connessione OAuth, l’URL di reindirizzamento verrà https://{dataCenter}.qualtrics.com/oauth-client-service/redirect, in cui {dataCenter} rappresenta il valore associato all’account. Consultare questa pagina per maggiori dettagli sulla ricerca del centro dati del tuo account.

Per eseguire l’autenticazione utilizzando OAuth 2.0:

aggiunta di un nuovo account OAuth

  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.
Qtip: per gli utenti che configurano le credenziali Google OAuth, includere il seguente parametro alla fine del punto di accesso token: “?prompt=consenso.” Se si dispone di parametri di query esistenti, il punto interrogativo non è necessario.
Consiglio Q: se riscontri problemi di connessione con Snowflake, assicurati che gli intervalli IP di Qualtrics siano inclusi nella lista di elementi consentiti.

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.
il pulsante Rinomina e rimuovi accanto a un cliente

Qtip: puoi solo rinominare o rimuovere le credenziali che hai aggiunto da solo.
Avvertimento: prestare attenzione durante l’eliminazione delle credenziali. Eventuali workflow che utilizzano le credenziali smetteranno di funzionare quando vengono eliminate.

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.
    aggiunta di un token API come intestazione
  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.
    selezione del campo del token API per lintestazione del token

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.
    Selezione di unattività del servizio Web
  2. Selezionare Autenticato.
    La finestra successiva mostra due opzioni: servizio Web autenticato e non autenticato
  3. Fare clic su Successivo.
  4. Aggiungere un account utente.
    Pulsante per aggiungere account utente nella parte superiore sinistra della pagina successiva della finestra

    Qtip: un Amministratore della licenza può connettersi a un account utilizzando la pagina Estensioni.
    Visualizzazione dell’estensione del servizio Web nella scheda Estensioni della pagina di amministrazione
  5. Selezionare un tipo di connessione e immettere le credenziali.
    credenziali del servizio Web
  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.
Qtip: la validità delle chiavi mTLS non può essere testata finché 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 immesse in modo errato. Provare a testare il servizio Web prima di rendere produttivo il workflow.

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:

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.

Qtip: se si sta modificando un’attività di servizio Web esistente, tutti i comandi curl importati sovrascriveranno le configurazioni precedenti.
Qtip: se ti interessa saperne di più sul curl rispetto a quanto coperto di seguito, ti consigliamo di leggere una risorsa al di fuori del supporto Qualtrics, come la documentazione di IBM.

Parametri di comando Curl supportati

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

Parametro Descrizione Comando Curl Esempio
URL L’endpoint o la risorsa con cui il servizio Web deve interagire. URL completo. https://datacenter.qualtrics.com/API/v3/directories/
Metodo HTTP Opzioni come GET, POST, PUT e così via. --X <command> o --richiesta <command> Esempio 1: --X GETExample
2: --request PUT
Intestazioni Intestazioni personalizzate. --H o --header Esempio 1: --header 'Accept: application/json'
Esempio 2: --header 'Content-Type: application/json'
Corpo Corpo (o payload) delle richieste POST. --d o --dati  --data '{

“descrizione”: “Elenca tutti i bug aperti”,

“jql”: “type = Bug e la risoluzione è vuota”,

“nome”: “Tutti i bug aperti”

}’

Formato JSON Sostituire la necessità di specificare la formattazione JSON nell’intestazione e nei dati. --json Questo comando curl sostituisce i seguenti 3 tag:

 

--data [arg]

--header "Content-Type: application/json"

--header "Accept: application/json"

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:

Nome Descrizione Esempio
Accetta Specificare i formati multimediali per la risposta. Accetta: applicazione/json
Tipo di contenuto In una richiesta, il tipo di contenuto specifica il tipo di media della risorsa inviata al server. Nella risposta, il tipo di contenuto indica il tipo di media della risorsa racchiuso nel corpo del messaggio. Tipo di contenuto: application/json
Autorizzazione Fornire credenziali per l’accesso a una risorsa protetta. Autorizzazione: Bearer Token
ETag Fornire un identificatore univoco per una versione specifica di una risorsa. ETag: "123456"
Lunghezza contenuto Impostare le dimensioni del corpo dell’entità nel messaggio. Lunghezza del contenuto: 1024
Origine Indicare l’origine della richiesta. Ciò può essere utile con Cross-Origin Resource Sharing (CORS). Origine: https://example.com

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.
Consiglio Q: se si tenta di importare un comando curl con parametri non supportati, verrà visualizzato un messaggio di errore che elenca i parametri non supportati utilizzati. Verrà data la possibilità di continuare a importare il comando curl con i parametri non supportati rimossi.

Importazione dei comandi Curl

  1. Durante la configurazione dell’attività del servizio Web, fare clic su Importa cURL.
    Pulsante che dice di ottenere un inizio importando i comandi curl
  2. Incollare il comando curl nella casella.
    Incollare un comando curl nel documento

    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.
Consiglio Q: si consiglia di ricontrollare i campi prima di attivare il flusso di lavoro.

FAQ

Molte delle pagine di questo sito sono state tradotte dall'originale in inglese mediante traduzione automatica. Sebbene in Qualtrics abbiamo profuso il massimo impegno per avere le migliori traduzioni automatiche possibili, queste non sono mai perfette. Il testo originale inglese è considerato la versione ufficiale, e qualsiasi discrepanza tra questo e le traduzioni automatiche non è legalmente vincolante.