Web-Service-Aufgabe

Informationen zur Aufgabe

Die Aufgabe ist nützlich, wenn Sie Erfahrung mit der API haben und verschiedene Workflows in der Qualtrics oder in einem externen Webdienst Auslöser möchten, wenn der Befragte:r die Umfrage abschließt. Wenn in Ihrer Umfrage beispielsweise die Kontakt des Befragte:r erfasst werden, kann eine Aufgabe die Kontakt anlegen API zum Hinzufügen des Befragte:r zu einer Kontaktliste.

Wir empfehlen auch, diese Web-Service-bezogenen Seiten zu besuchen, um weitere Unterstützung und Hintergrund zu erhalten:

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

Aufgabe einrichten

Je nachdem, wie Sie Ihre Körperparameter formatieren möchten, wird sich das Setup geringfügig unterscheiden. Wenn Sie das JSON oder XML verwenden, geben Sie Ihren Hauptteil in das Feld Hauptteil Abschnitt. Wenn Sie URL-kodiert bevorzugen, können Sie Parameter als Query-String an die URL Feld.

1. Legen Sie einen Workflow an (oder wählen Sie einen vorhandenen aus). in Ihrem Projekt oder in der Seite „Standalone Workflows“.
   
2. Stellen Sie sicher, dass Sie im Ihre Workflows Abschnitt.
3. Klicken Sie auf Workflow anlegen .
4. Ermitteln Sie die Plan oder die Ereignis die Ihre Aufgabe auslöst. (Vergleich anzeigen .)
5. Klicken Sie auf Aufgabe hinzufügen und wählen Sie WebService.
   
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 Kennwort und Benutzername), API und OAuth.
   • Nicht authentifiziert: Führen Sie eine Webdienstanforderung ohne Authentifizierung aus.
7. Klicken Sie auf Weiter.
8. Wenn Sie eine authentifizierte Anforderung ausgewählt haben, wählen Sie Ihre Berechtigungsanmeldedaten aus der Liste aus, oder klicken Sie auf Benutzerkonto hinzufügen , um neue Anmeldeinformationen hinzuzufügen. Siehe Berechtigungs-Credentials hinzufügen für weitere Informationen.
   
   Tipp: Sie können alle Anmeldeinformationen auswählen, die Sie zuvor hinzugefügt haben, oder Anmeldeinformationen, die von einem Instanz in hinzugefügt wurden. Erweiterungen Registerkarte.
9. Klicken Sie auf Weiter.
10. Wenn Sie eine Anforderung im Curl-Format haben, können Sie sie importieren, um Ihren Webdienst automatisch einzurichten. Siehe Curl-Befehle verwenden für Details.
    
11. Fügen Sie bei Bedarf eine Aufgabe ganz oben in Ihrer Aufgabe. Dies ist eine Beschreibung, die das Ziel der Aufgabe erläutert.
12. Wählen Sie Ihre Webdienste aus. Anforderung Methode. Siehe Web-Service-Methoden für weitere Informationen zu den einzelnen Methoden.
    
    Tipp: Wenn Sie die Qualtrics verwenden, die Dokumentation wird Ihnen mitteilen, welche Art von Anfrage verwendet werden soll.
    Achtung: WebService-Aufgaben lassen keine URL für Nicht-GET-Anforderungen zu. Für GET-Anfragen ist nur eine Umleitung zulässig.
13. Geben Sie die URL für Ihre Anforderung ein.
    Tipp: Sie können die Domänen einschränken, mit denen die Aufgabe eine Verbindung herstellen kann, indem Sie die Domänen in Ihrem angeben. Erweiterungsdomäneneinstellungen.
14. Klicken Sie bei Bedarf auf Kopfzeile hinzufügen , um eine Kopfzeile hinzuzufügen. Geben Sie die Schlüssel und Wert. Um eine Kopfzeile zu entfernen, klicken Sie auf das Papierkorb weiter der Kopfzeile.
    Tipp: Verwenden Sie das Symbol dynamischer Text. {a}, einfügen dynamischer Text um Werte aus Umfrage oder vorherigen Aufgaben im Workflow abzurufen.
    Achtung: Wenn Sie die Qualtrics verwenden, müssen Sie Ihr API-Token über den Header einschließen. Siehe Hinzufügen einer Kopfzeile für Qualtrics für weitere Informationen.
15. Wenn Sie Post, Put oder Patch wählen, müssen Sie das Format Ihres Körpers auswählen. Zu den Optionen gehören JSON, URL-kodiert, XML, und Nur-Text.
    
    
16. Legen Sie fest, wie Sie den Hauptteil Ihrer Anfrage angeben möchten. Sie können den Hauptteil wie folgt hinzufügen: Schlüssel-Wert-Paare oder Freitext.
17. Wenn Sie Schlüssel-Wert-Paare ausgewählt haben, fügen Sie die Schlüssel und die zugehörigen Wert. Klicken Sie auf Schlüssel-Wert-Paar hinzufügen um zusätzliche Parameter hinzuzufügen.
    Achtung: Für POST, PUT, und PATCH -Anforderungen müssen Sie für jedes Schlüssel-Wert-Paar einen Datentyp angeben.
18. Wählen Sie eine Datentyp.
    • 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 vorliegen.
    • Nummer: 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 systemeigenen Datentyp für Ihre Daten verwenden möchten. Wenn ein Datentyp nicht gefunden werden kann, wird standardmäßig der Zeichenfolge Typ.
      Tipp: Wir empfehlen, einen der anderen Datentypen auszuwählen, um sicherzustellen, dass Ihre Daten korrekt konvertiert werden.
      Achtung: Schlüssel-Wert-Paare, die vor dem 16. September 2022 konfiguriert wurden, haben den Datentyp Systemstandard.
    Tipp: Die Datentyp Feld ist nur verfügbar, wenn Sie JSON und Schlüssel-Wert-Paare in den Schritten 13-14.
19. Wählen Sie aus, was geschieht, wenn der Datentyp nicht gecastet werden kann.
    • Nehmen Sie kein Casting für einen Datentyp vor, und kennzeichnen Sie ihn als Fehler: Wenn der Datentyp nicht gecastet werden kann, wird kein Datentyp gecastet, und die Aufgabe schlägt fehl. Dies können Sie in der Laufhistorie Registerkarte.
    • Datentyp in Systemstandard umwandeln: Wenn der Datentyp nicht gecastet werden kann, wird der Datentyp auf Systemstandard.
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 überhaupt nicht ein, oder geben Sie den Begriff „null“ ein, um leere Werte anzugeben. Wir empfehlen, das Feld auszuschließen.
    Tipp: Wenn eine Aufgabe auf einen ungültigen JSON stößt, schlägt die Aufgabe nicht fehl. Stattdessen wird die ungültige JSON in einen String konvertiert und als “text”-Eigenschaft in einem neuen JSON gesichert. Auf diese Weise können Sie den ungültigen Text sehen, sobald die Aufgabe die Verarbeitung beendet hat.
    Achtung: Web-Service-Aufgaben unterstützen derzeit keine Kommentare.
21. Um Ihren Webdienst zu testen, wählen Sie 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 oder nicht, und die resultierende JSON oder XML, wenn sie erfolgreich war.
22. Klicken Sie auf Benutzerdefinierten Pfad hinzufügen um JSON oder XML hinzuzufügen. Mit diesen Pfaden können Sie die Ergebnisse Ihres Web-Service in dynamischer Text verwenden, um sie mit anderen Aufgaben in Ihrem Workflow zu verwenden, z.B. einem Aufgabe. Wenn Sie Ihren Webdienst getestet haben, haben Sie hier möglicherweise automatisch Werte, da Qualtrics diese automatisch aus den Ergebnisse zieht.
    Tipp: Klicken Sie auf Benutzerdefinierten Pfad hinzufügen um zusätzliche Pfade hinzuzufügen, oder klicken Sie auf den Papierkorb weiter einem Pfad, um ihn zu löschen.
23. Wenn Sie mit dem Einrichten Ihres Workflow fertig sind, klicken Sie auf Sichern.

Berechtigungs-Credentials hinzufügen

In diesem Abschnitt wird erläutert, wie Berechtigungsanmeldeinformationen für die Aufgabe hinzugefügt werden. Sie können Anmeldeinformationen hinzufügen, indem Sie die Einfach, API oder OAuth 2.0 Methode. Um Anmeldeinformationen hinzuzufügen, klicken Sie auf Benutzerkonto hinzufügen aus dem Fenster zur Auswahl der Anmeldeinformationen.

Basis

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

1. Geben Sie Ihren Anmeldeinformationen eine Bezeichnung. Dies ist nur für Ihre organisatorischen Zwecke vorgesehen.
2. Auswählen Grundlegend als Verbindungstyp.
3. Geben Sie Folgendes ein: Benutzername für die Authentifizierung erforderlich.
4. Geben Sie Folgendes ein: Kennwort für die Authentifizierung.
5. Klicken Sie auf Benutzerkonto verbinden .

API-Schlüssel

Mit der API können Sie sich mit einem statischen API-Token authentifizieren.

1. Geben Sie Ihrem Benutzerkonto eine Bezeichnung. Dies ist nur für Ihre organisatorischen Zwecke vorgesehen.
2. Auswählen API als Verbindungstyp.
3. Geben Sie Folgendes ein: API wird für die Authentifizierung verwendet.
4. Klicken Sie auf Benutzerkonto verbinden .

OAuth 2.0

Die OAuth-2.0-Berechtigung erspart die Verwendung statischer API oder eines einfachen Benutzernamens und Kennworts für die Integration mit Drittanbieterplattformen. Die Aufgabe unterstützt zwei verschiedene OAuth-2.0-Autorisierungstypen: Berechtigungscode und Client-Anmeldeinformationen.

Sie können die OAuth-2.0-Berechtigung verwenden, um eine nahtlose Integration mit vielen Drittanbieterplattformen zu ermöglichen. Die Qualtrics folgt der offiziellen OAuth-Spezifikation. Einige externe Systeme können jedoch etwas andere Konfigurationen haben, was zu Inkompatibilitäten mit der OAuth-2.0-Berechtigung in der Aufgabe führt.

Die folgenden Integrationen sind einige Beispiele, die für die Arbeit mit OAuth2.0 vollständig verifiziert wurden:

• Salesforce mit der Autorisierungscode-Methode.
• Jira mit der Autorisierungscode-Methode.
• Zoom mit der Berechtigungscode-Methode.

So authentifizieren Sie sich mit OAuth 2.0:

1. Geben Sie Ihrem Benutzerkonto eine Bezeichnung. Dies ist nur für Ihre eigenen organisatorischen Zwecke vorgesehen.
2. Auswählen OAuth als Verbindungstyp.
3. Wählen Sie Ihre Förderungsartoder wie das Zugriffstoken abgerufen wird. Sie können Folgendes wählen:
   • Autorisierungscode
   • Client-Anmeldedaten
4. Geben Sie Folgendes ein: Client-ID und Geheimer Client-Schlüssel.
5. Geben Sie Folgendes ein: Tokenendpunkt.
6. Wenn Sie den Berechtigungscode als Erteilungsart ausgewählt haben, geben Sie den Berechtigungsendpunkt.
7. Klicken Sie auf Benutzerkonto verbinden .

&Umbenennen; Anmeldeinformationen werden entfernt

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

Hinzufügen einer Kopfzeile für Qualtrics

Bei Verwendung des Qualtrics müssen Sie einschließen Ihr API-Token als Header in Ihrem Webservice.

1. Einrichten Ihre Aufgabe, wählen Sie Ihre Anmeldeinformationen aus, und wählen Sie Ihre Anforderung aus.
   
2. Geben Sie im Abschnitt Kopfzeilen Folgendes ein: X-API-TOKEN als Schlüssel ein.
3. Klicken Sie für den Wert auf das Symbol dynamischer Text. {a}.
4. Wählen Sie Ihre Anmeldeinformationen aus der Liste aus.
   

Gegenseitige TLS

Gegenseitige Transportschichtsicherheit (mTLS) ist eine zusätzliche, optionale Sicherheitsschicht zusätzlich zu API (z.B. API oder OAuth). Gegenseitiges TLS stellt sicher, dass sowohl die Person, die eine Verbindung zu einem API/Web-Service herstellt, als auch die API/der Web-Service selbst über sicheren, verschlüsselten Datenverkehr in beide Richtungen verfügen. Sobald mTLS aktiviert ist, müssen alle Anforderungen das richtige Client-Zertifikat enthalten, damit die Anforderungen erfolgreich sind. Wenn ein Aufrufer eine Anforderung mit einem ungültigen oder fehlenden Client-Zertifikat stellt, blockiert das API, das er aufruft, die Anforderung.

Anforderungen

Jeder Service unterscheidet sich darin, ob er mTLS unterstützt und welche Formate er in wichtige Informationen bereitstellt. Es wird garantiert, dass wir mTLS nur für Services unterstützen, die unseren Anforderungen entsprechen:

• Einen privaten Schlüssel bereitstellen
• Privater Schlüssel kann in PKCS8 formatiert werden
• Zertifikat bereitstellen
• Zertifikat kann in X.509 formatiert werden

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

mTLS wird nur unterstützt für Authentifiziert Webdienste erstellt in Workflows. Alle drei Authentifizierungsmethoden werden unterstützt (Standard, API und OAuth2.0).

mTLS hinzufügen

1. Legen Sie Ihre Aufgabe.
   
2. Auswählen Authentifiziert.
   
3. Klicken Sie auf Weiter.
4. Fügen Sie ein Benutzerkonto.
   
   Tipp: A Instanz kann eine Verbindung zu einem Benutzerkonto herstellen, indem Sie die Erweiterungen Seite.
   
5. Wählen Sie eine Verbindungstyp und geben Sie Ihre Anmeldeinformationen ein.
   
6. Auswählen mTLS aktivieren .
7. Die Privater 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 in einem anderen Format vorliegt, können Sie dieses Format mit einem anderen Programm ändern.
   Tipp: Wenn Sie die Qualtrics mit Ihrem Webdienst verwenden möchten, finden Sie weitere Informationen unter. unsere API 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 einschließen, z.B. „Privaten Schlüssel beginnen“ und „Privaten Schlüssel beenden“.
8. Die Öffentlicher Schlüssel ist das mTLS. Dieser Wert muss im X.509-Format vorliegen.
   Tipp: Wenn Sie die Qualtrics mit Ihrem Webdienst verwenden möchten, finden Sie weitere Informationen unter. unsere API zu mTLS. In dieser Dokumentation erfahren Sie, wie Sie das Zertifikat abrufen. Wenn Sie den Wert in Qualtrics einfügen, müssen Sie Bindestriche wie „Zertifikat beginnen“ und „Zertifikat beenden“ einfügen.
9. Wenn Sie fertig sind, klicken Sie auf Benutzerkonto verbinden .
10. Fahren Sie mit der Einrichtung Ihres Webdienstes fort..

Curl-Befehle verwenden

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

Viele API stellen häufig Curl-Beispiele bereit, die Sie verwenden können. Wenn Sie diese Befehle kopieren und importieren können, kann das Einrichten von Web-Services viel schneller und einfacher werden.

Beispiele für Curl-Anforderungen finden Sie auf der rechten Seite zu jedem dieser API:

• Mailingliste abrufen
• Erinnerung anlegen
• Kontakt aktualisieren
• Benutzer in Gruppe auflisten

Für eine GET-Anforderung kann der curl-Befehl so einfach sein wie curl api. 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 von der Qualtrics unterstützt werden:

Allgemeine Kopfparameter

Oben wurde erwähnt, dass Sie Curl-Befehle verwenden können, um Header zu definieren. Header dienen verschiedenen Zwecken in der kommunikation, z.B. der Bereitstellung von Informationen über die Anfrage und der Steuerung der Authentifizierung. Die spezifischen Kopfzeilen, die Sie verwenden, hängen von den Anforderungen der von Ihnen verwendeten Anwendung oder API ab.

Im Folgenden finden Sie einige Beispiele für Kopfparameter:

Nicht unterstützte Parameter

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

• --Cookie um Cookies mit der Anfrage zu senden.
• --L oder --Standort für die folgenden Weiterleitungen.
• --max-time zum Festlegen der maximalen Anfragezeit.
• --o oder --Ausgabe , um die Antwort auf eine Datei zu speichern.
• --unsicher um unsichere Verbindungen zuzulassen.
• --A oder --User-Agent , um den Benutzeragenten anzugeben.

Curl-Befehle importieren

1. Klicken Sie während der Einrichtung Ihrer Aufgabe 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: Achten Sie auf Teile der Anfrage, die Sie mit Ihren eigenen Informationen ausfüllen müssen. Im obigen Screenshot würden Sie beispielsweise „API“ durch Ihren API-Token.

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

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

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

FAQs