Web-Service-Aufgabe

Informationen zur Webdienstaufgabe

Die Webdienstaufgabe ist nützlich, wenn Sie Erfahrung mit der API haben und verschiedene Workflows innerhalb der Qualtrics-Software oder einen externen Webdienst auslösen möchten, wenn der Umfrageteilnehmer die Umfrage abgeschlossen hat. Wenn in Ihrer Umfrage beispielsweise die Kontaktinformationen des Umfrageteilnehmers erfasst werden, kann eine Webserviceaufgabe den API-Aufruf zum Erstellen von Kontakten verwenden, um den Antwortenden zu einer Kontaktliste hinzuzufügen.

Wir empfehlen außerdem, die folgenden Webservice-bezogenen Seiten zu besuchen, um weitere Unterstützung und Hintergrundinformationen zu erhalten:

• Qualtrics Developer Hub
• Web-Service-Methoden
• API-Dokumentation
• Übergabe von Informationen über Query-Strings
• Dynamischer Text

Web-Service-Aufgabe einrichten

Je nachdem, wie Sie Ihre Textparameter formatieren möchten, unterscheiden sich die Einstellungen geringfügig. Wenn Sie das JSON- oder XML-Format verwenden, geben Sie Ihren Hauptteil in der Sektion Body ein. Wenn Sie es bevorzugen, URL-kodiert zu verwenden, können Sie dem URL-Feld Parameter als Query-String hinzufügen.

1. Legen Sie einen Workflow in Ihrem Projekt oder auf der Standalone-Workflow-Seite an (oder wählen Sie einen vorhandenen aus).
   
2. Stellen Sie sicher, dass Sie sich im Abschnitt Ihre Workflows befinden.
3. Klicken Sie auf Workflow erstellen.
4. Legen Sie den Zeitplan oder das Ereignis fest, das Ihre Aufgabe auslöst. (Siehe Vergleich.)
5. Klicken Sie auf Aufgabe hinzufügen, und wählen Sie WebService aus.
   
6. Wählen Sie Ihre Authentifizierungsmethode aus. Folgende Optionen sind verfügbar:
   
   • Authentifiziert: Führen Sie eine authentifizierte Webdienstanforderung aus. Zu Ihren Authentifizierungsoptionen gehören Basic (mit einem Kennwort und einem Benutzernamen), API-Schlüssel und OAuth.
   • Nicht authentifiziert: Führen Sie eine Webdienstanforderung ohne Authentifizierung durch.
7. Klicken Sie auf Weiter.
8. Wenn Sie eine authentifizierte Anforderung ausgewählt haben, wählen Sie Ihre Autorisierungsanmeldedaten aus der Liste aus, oder klicken Sie auf Benutzerkonto hinzufügen, um neue Anmeldeinformationen hinzuzufügen. Weitere Informationen finden Sie unter Berechtigungs-Credentials hinzufügen.
   
   Tipp: Sie können Anmeldeinformationen auswählen, die Sie zuvor hinzugefügt haben, oder Anmeldeinformationen, die ein Administrator auf der Registerkarte Erweiterungen hinzugefügt hat.
9. Klicken Sie auf Weiter.
10. Wenn Sie eine kurvenformatierte Anforderung haben, können Sie sie importieren, um Ihren Webdienst automatisch einzurichten. Weitere Informationen finden Sie im Abschnitt Curl-Befehle verwenden.
    
11. Fügen Sie bei Bedarf oben in Ihrer Aufgabe eine Aufgabenzusammenfassung hinzu. Dies ist eine Beschreibung, die das Ziel der Aufgabe erläutert.
12. Wählen Sie die Request-Methode Ihres Webdienstes. Weitere Informationen zu den einzelnen Methoden finden Sie unter Web-Service-Methoden.
    
    Tipp: Wenn Sie die Qualtrics-API verwenden, erfahren Sie in der Dokumentation, welche Art von Anfrage Sie verwenden sollten.
    Achtung: Web-Service-Aufgaben lassen keine URL-Umleitungen für Nicht-GET-Anforderungen zu. Für GET-Requests ist nur ein Redirect erlaubt.
13. Geben Sie die URL für Ihre Anfrage ein.
    Tipp: Sie können die Domänen einschränken, mit denen die Webdienstaufgabe eine Verbindung herstellen kann, indem Sie die Domänen in Ihren Erweiterungsdomäneneinstellungen angeben.
14. Klicken Sie bei Bedarf auf Kopfzeile hinzufügen, um eine Kopfzeile hinzuzufügen. Geben Sie den Schlüssel und den Wert an. Um eine Kopfzeile zu entfernen, klicken Sie auf das Papierkorbsymbol neben der Kopfzeile.
    Tipp: Verwenden Sie das Symbol {a}, um dynamischen Text einzufügen, um Werte aus Umfrageantworten oder vorherigen Aufgaben im Workflow abzurufen.
    Achtung: Wenn Sie die Qualtrics-API verwenden, müssen Sie Ihr API-Token über die Kopfzeile einfügen. Weitere Informationen finden Sie unter Hinzufügen eines Headers für Qualtrics-API-Anfragen.
    Achtung: Für POST-, PUT- und PATCH-Requests müssen Sie für jedes Schlüssel-Wert-Paar einen Datentyp angeben.
    Achtung: Web-Service-Aufgaben unterstützen derzeit keine Kommentare/Texte im Hauptteil, der Escapesequenzen enthält.
15. Wenn Sie Post, Put oder Patch wählen, müssen Sie das Format Ihres Körpers wählen. Zu den Optionen gehören JSON, URL-kodiert, XML und Nur-Text.
    
    
    Tipp: Klartext kann nur als Freitext angegeben werden. Wenn Sie die Option für JSON-Freitext verwenden, werden Eingaben nicht maskiert. Das bedeutet, dass beispielsweise eine dynamische Texteingabe mit doppelten Anführungszeichen oder Zeilenumbruchszeichen (Beispiel: \n) dazu führt, dass der JSON-Hauptteil ungültig wird und nicht ordnungsgemäß ausgeführt wird. Eine Alternative besteht darin, entweder die Schlüssel-Wert-Paar-Option zu verwenden oder eine Code-Aufgabe zu verwenden, um den Text zu bereinigen oder zu maskieren, der in die Webdienstaufgabe eingefügt werden soll.
16. Legen Sie fest, wie Sie den Hauptteil Ihrer Anfrage angeben möchten. Sie können den Hauptteil als Schlüssel-Wert-Paare oder Freitext hinzufügen.
17. Wenn Sie Schlüssel-Wert-Paare ausgewählt haben, fügen Sie den Schlüssel und den zugehörigen Wert hinzu. Klicken Sie auf Schlüssel-Wert-Paar hinzufügen, um zusätzliche Parameter hinzuzufügen.
18. Wählen Sie einen Datentyp aus.
    • Boolesch: Wählen Sie diesen Datentyp aus, wenn Ihre Daten einen von zwei möglichen Werten haben.
    • JSON: Wählen Sie diesen Datentyp aus, wenn Ihre Daten im JSON-Format vorliegen.
    • Zahl: Wählen Sie diesen Datentyp aus, wenn Ihre Daten numerisch sind.
    • Zeichenfolge: Wählen Sie diesen Datentyp aus, wenn Ihre Daten im Textformat vorliegen.
    • Systemstandard: Wählen Sie diesen Datentyp aus, wenn Sie den nativen Datentyp für Ihre Daten verwenden möchten. Wenn kein Datentyp gefunden wird, wird standardmäßig der Typ String verwendet.
      Tipp: Wir empfehlen, einen der anderen Datentypen auszuwählen, um sicherzustellen, dass Ihre Daten korrekt gecastet werden.
      Achtung: Schlüssel-Wert-Paare, die vor dem 16. September 2022 konfiguriert wurden, haben den Datentyp Systemstandard.
    Tipp: Das Feld Datentyp ist nur verfügbar, wenn Sie JSON- und Schlüssel-Wert-Paare in den Schritten 13-14 auswählen.
19. Wählen Sie aus, was passiert, wenn der Datentyp nicht umgewandelt werden kann.
    • Geben Sie keinen Datentyp ein, und kennzeichnen Sie ihn als Fehler: Wenn der Datentyp nicht umgewandelt werden kann, wird kein Datentyp gecastet, und die Aufgabe schlägt fehl. Dies wird auf der Registerkarte Ausführungsverlauf angezeigt.
    • Cast the data type to system default: Wenn der Datentyp nicht umgewandelt werden kann, wird der Datentyp auf System Default gesetzt.
20. Wenn Sie Freitext ausgewählt haben, geben Sie Ihre Textparameter in Ihrem ausgewählten Format ein.
    
    Achtung: Sie sollten dieses Feld nicht leer lassen oder Schlüssel ohne Werte haben. Schließen Sie stattdessen entweder das Feld gar nicht ein, oder geben Sie den Begriff “null” ein, um leere Werte anzugeben. Wir empfehlen, das Feld auszuschließen.
21. Um Ihren Webdienst zu testen, klicken Sie auf Test ausführen.
    
    Tipp: Nachdem Sie auf Test ausführen geklickt haben, wird das Ergebnis Ihrer Anforderung angezeigt, das Sie darüber informiert, ob sie erfolgreich war, und die resultierende JSON oder XML, wenn sie erfolgreich war.
22. Klicken Sie auf Benutzerdefinierten Pfad hinzufügen, um JSON- oder XML-Pfade hinzuzufügen. Mit diesen Pfaden können Sie die Ergebnisse Ihres Webdienstes in dynamischem Text verwenden, der mit anderen Aufgaben in Ihrem Workflow verwendet werden kann, z.B. einer Code-Aufgabe. Wenn Sie Ihren Webdienst getestet haben, haben Sie hier möglicherweise automatisch Werte, da Qualtrics sie automatisch aus den Ergebnissen zieht.
    Tipp: Klicken Sie auf Benutzerdefinierten Pfad hinzufügen, um zusätzliche Pfade hinzuzufügen, oder klicken Sie auf den Papierkorb neben einem Pfad, um ihn zu löschen.
23. Wenn Sie die Einrichtung Ihres Workflows abgeschlossen haben, klicken Sie auf Speichern.

Berechtigungsanmeldedaten hinzufügen

In diesem Abschnitt wird erläutert, wie Sie Berechtigungsanmeldeinformationen für die Web-Service-Aufgabe hinzufügen. Sie können Anmeldeinformationen mithilfe der Basic-, API-Schlüssel- oder OAuth-2.0-Methode hinzufügen. Um Anmeldeinformationen hinzuzufügen, klicken Sie im Fenster zur Auswahl der Anmeldedaten auf Benutzerkonto hinzufügen.

Basis

Für die Standardauthentifizierung müssen Sie sich mit dem Benutzernamen und dem Kennwort Ihres Kontos anmelden.

1. Geben Sie einen Namen für Ihre Anmeldeinformationen ein. Dies ist nur für Ihre organisatorischen Zwecke vorgesehen.
2. Wählen Sie Basic als Verbindungstyp.
3. Geben Sie den für die Authentifizierung erforderlichen Benutzernamen ein.
4. Geben Sie das Kennwort für die Authentifizierung ein.
5. Klicken Sie auf Konto verbinden.

API-Schlüssel

Mit der API-Schlüssel-Authentifizierung können Sie sich mit einem statischen API-Token authentifizieren.

1. Geben Sie Ihrem Konto einen Namen. Dies ist nur für Ihre organisatorischen Zwecke vorgesehen.
2. Wählen Sie API-Schlüssel als Verbindungstyp.
3. Geben Sie den für die Authentifizierung verwendeten API-Token ein.
4. Klicken Sie auf Konto verbinden.

OAuth 2.0

Die OAuth-2.0-Berechtigung erspart die Verwendung statischer API-Token oder des Basisbenutzernamens und -kennworts für die Integration mit Drittanbieterplattformen. Die Web-Service-Aufgabe unterstützt zwei verschiedene OAuth-2.0-Berechtigungstypen: Berechtigungscode und Client-Credentials.

Sie können die OAuth-2.0-Berechtigung für die nahtlose Integration mit vielen Drittanbieterplattformen verwenden. Die Qualtrics-Webservice-Implementierung folgt der offiziellen OAuth-Spezifikation. Einige externe Systeme können jedoch geringfügig unterschiedliche Konfigurationen aufweisen, was zu Inkompatibilitäten mit der OAuth-2.0-Berechtigung in der Web-Service-Aufgabe führt.

Die folgenden Integrationen sind einige Beispiele, die vollständig verifiziert wurden, um mit OAuth2.0 zu funktionieren:

• Salesforce unter Verwendung der Berechtigungscode-Methode.
• Jira unter Verwendung der Berechtigungscode-Methode.
• Zoomen Sie mithilfe der Berechtigungscodemethode.

So authentifizieren Sie sich mit OAuth 2.0:

1. Geben Sie Ihrem Konto einen Namen. Dies ist nur für Ihre eigenen organisatorischen Zwecke vorgesehen.
2. Wählen Sie OAuth als Verbindungstyp.
3. Wählen Sie Ihre Erteilungsart aus oder wie der Zugriffstoken abgerufen werden soll. Sie können Folgendes wählen:
   • Autorisierungscode
   • Client-Anmeldedaten
4. Geben Sie die Client-ID und den geheimen Client-Schlüssel ein.
5. Geben Sie den Tokenendpunkt ein.
6. Wenn Sie Berechtigungscode als Erteilungsart ausgewählt haben, geben Sie den Berechtigungsendpunkt ein.
7. Klicken Sie auf Konto verbinden.

&Umbenennen; Anmeldeinformationen werden entfernt

Um den Namen Ihrer Anmeldeinformationen zu bearbeiten, klicken Sie auf die drei Punkte neben dem Konto. Um Anmeldeinformationen zu entfernen, klicken Sie auf Konto entfernen.

Hinzufügen einer Kopfzeile für Qualtrics-API-Anfragen

Wenn Sie die Qualtrics-API verwenden, müssen Sie Ihr API-Token als Header in Ihren Webdienst einbinden.

1. Richten Sie Ihre Web-Service-Aufgabe ein, wählen Sie Ihre Anmeldeinformationen aus, und wählen Sie Ihre Anforderung aus.
   
2. Geben Sie im Abschnitt Überschriften X-API-TOKEN als Schlüssel ein.
3. Klicken Sie für den Wert auf das Symbol für den dynamischen Text {a}.
4. Wählen Sie Ihre Anmeldeinformationen aus der Liste aus.
   

Gegenseitige TLS

Mutual Transport Layer Security (mTLS) ist eine zusätzliche, optionale Sicherheitsschicht zusätzlich zu Standard-API-Authentifizierungsmechanismen (wie API-Token oder OAuth). Die gegenseitige TLS-Authentifizierung stellt sicher, dass sowohl die Person, die sich mit einer API/einem Web-Service verbindet, als auch die API bzw. der Web-Service selbst einen sicheren, verschlüsselten Datenverkehr in beide Richtungen haben. Sobald mTLS aktiviert ist, müssen alle Anforderungen das richtige Client-Zertifikat vorlegen, damit Anforderungen erfolgreich sind. Wenn ein Aufrufer einen Request mit einem ungültigen oder fehlenden Client-Zertifikat sendet, blockiert das API, das er aufrufen möchte, den Request.

Anforderungen

Jeder Service variiert darin, ob er mTLS unterstützt und in welchem Format er wichtige Informationen bereitstellt. Wir garantieren, mTLS nur für Services zu unterstützen, die unseren Anforderungen entsprechen:

• Geben Sie einen privaten Schlüssel an
• Privater Schlüssel kann in PKCS8 formatiert werden
• Stellen Sie ein Zertifikat bereit
• Zertifikat kann in X.509 formatiert werden

Die öffentlichen Qualtrics-APIs unterstützen mTLS wie oben beschrieben.

mTLS wird nur für authentifizierte Webdienste unterstützt, die in Workflows erstellt wurden. Alle drei Authentifizierungsmethoden werden unterstützt (Standard, API-Schlüssel und OAuth2.0).

mTLS hinzufügen

1. Legen Sie Ihre Web-Service-Aufgabe an.
   
2. Wählen Sie Authentifiziert.
   
3. Klicken Sie auf Weiter.
4. Fügen Sie ein Benutzerkonto hinzu.
   
   Tipp: Ein Administrator kann über die Seite Erweiterungen eine Verbindung zu einem Konto herstellen.
   
5. Wählen Sie einen Verbindungstyp aus, und geben Sie Ihre Anmeldedaten ein.
   
6. Wählen Sie mTLS aktivieren.
7. Der private Schlüssel kann als eindeutige ID des Clients betrachtet werden, der versucht, eine Verbindung herzustellen. Dieser Wert muss im PKCS8-Format vorliegen.
   Tipp: Wenn Ihr Schlüssel ein anderes Format hat, können Sie es mit einem anderen Programm ändern, um dieses Format zu ändern.
   Tipp: Wenn Sie planen, die Qualtrics-API mit Ihrem Web-Service zu verwenden, lesen Sie unsere API-Dokumentation zu mTLS. In dieser Dokumentation erfahren Sie, wie Sie den privaten Schlüssel abrufen. Wenn Sie den Wert in Qualtrics einfügen, müssen Sie Bindestriche einfügen, z.B. „Start privater Schlüssel“ und „Ende privater Schlüssel“.
8. Der öffentliche Schlüssel ist das mTLS-Zertifikat. Dieser Wert muss im X.509-Format vorliegen.
   Tipp: Wenn Sie planen, die Qualtrics-API mit Ihrem Web-Service zu verwenden, lesen Sie unsere API-Dokumentation zu mTLS. In dieser Dokumentation erfahren Sie, wie Sie das Zeugnis abrufen. Wenn Sie den Wert in Qualtrics einfügen, müssen Sie Bindestriche einfügen, z.B. „Zertifikat beginnen“ und „Zertifikat beenden“.
9. Wenn Sie fertig sind, klicken Sie auf Konto verbinden.
10. Fahren Sie mit der Einrichtung Ihres Webdienstes fort.

Curl-Befehle verwenden

Curl-Befehle sind eine von vielen Möglichkeiten, HTTP-Requests zu erstellen, und sind ein wertvolles Werkzeug, um Informationen über URLs hin und her zu übertragen. Sie können einen curl-Befehl importieren, während Sie Ihre Aufgabe so einrichten, dass verschiedene Webservicekonfigurationen automatisch ausgefüllt werden.

Viele API-Dokumente stellen häufig Curl-Beispiele bereit, die Sie verwenden können. Das Kopieren und Importieren dieser Befehle kann so die Einrichtung des Web-Service viel schneller und einfacher machen.

Einige Beispiele für Curl-Anforderungen finden Sie rechts in jedem dieser API-Dokumente:

• Mailingliste abrufen
• Erinnerungsverteilung anlegen
• Ansprechpartnervorgang aktualisieren
• Benutzer in Gruppe auflisten

Bei einer GET-Anforderung kann der curl -Befehl so einfach sein wie curl https://api.example.com/parameters. Für Curl-Befehle, die nicht so einfach sind, stellen wir einige allgemeine Parameter bereit.

Unterstützte Curl-Befehlsparameter

Im Folgenden finden Sie einige der Curl-Parameter, die die Qualtrics-Webdienstaufgabe unterstützt:

Allgemeine Kopfparameter

Oben wurde erwähnt, dass Sie Curl-Befehle verwenden können, um Header zu definieren. Header dienen verschiedenen Zwecken in der HTTP-Kommunikation, z.B. der Bereitstellung von Informationen über den Request und der Steuerung der Authentifizierung. Die spezifischen Header, die Sie verwenden, hängen von den Anforderungen der Anwendung oder des APIs ab, die bzw. das Sie verwenden.

Im Folgenden finden Sie einige Beispiele für Kopfparameter:

Nicht unterstützte Parameter

Alle Curl-Parameter, die oben nicht aufgeführt sind, werden nicht unterstützt. Im Folgenden finden Sie einige Beispiele für Curl-Befehlsformate, die Qualtrics-Webdienstaufgaben nicht unterstützen:

• --Cookie, um Cookies mit der Anfrage zu senden.
• --L oder --Standort für folgende Weiterleitungen.
• --max-time zum Festlegen der maximalen Anforderungszeit.
• --o oder --output zum Speichern der Antwort auf eine Datei.
• --unsicher, um unsichere Verbindungen zuzulassen.
• --A oder --user-agent, um den User-Agent anzugeben.

Curl-Befehle importieren

1. Klicken Sie während der Einrichtung Ihrer Webserviceaufgabe auf cURL importieren.
   
2. Fügen Sie den curl-Befehl in das Feld ein.
   
   Achtung: Stellen Sie sicher, dass Sie Ihre HTTP-Methode in Ihre Curl-Anforderung aufnehmen, insbesondere wenn Sie einen curl-Befehl von einer anderen Plattform kopieren.
   Tipp: Halten Sie Ausschau nach Teilen der Anfrage, die Sie mit Ihren eigenen Informationen ausfüllen müssen. Beispiel: Im obigen Screenshot würden Sie „API-Schlüssel“ durch Ihren API-Token ersetzen.

   Tipp: Sie können einen Befehl in einer einzelnen Zeichenfolge hinzufügen oder Zeilenumbrüche mit dem Escape-Zeichen ( \ ) markieren. Andere Zeilenmaskierungen (z.B. ^ ) werden nicht unterstützt. Im Folgenden finden Sie ein Beispiel für einen curl-Befehl mit unterstützten Escape-Zeichen:

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

3. Klicken Sie auf Importieren.
4. Web-Service-Felder werden automatisch gefüllt.

FAQs