API-Übersicht
Nicht löschen, enthält Stile, die auf den Artikel angewendet werden.
Wichtig
Wenn Sie noch nicht mit APIs vertraut sind, besuchen Sie die Hilfeseite Erste Schritte mit APIs .
Wichtig
Beginnend mit der Version 22.1 haben wir unsere öffentlichen Legacy-OAuth1-API-Endpunkte entfernt, da sie nicht FIPS-konformes SHA1-Hashing erfordern. Dies beinhaltet die Legacy-WCF-Endpunkte (Windows Communication Framework), Swagger für diese Legacy-Endpunkte und OAuth1-Middleware. Um die OAuth1-Endpunkte zu ersetzen, können Sie die OAuth2-Versionen der in 21.4 veröffentlichten Legacy-APIs verwenden, die FIPS-konform sind. Mit den OAuth2-APIs stehen Ihnen dieselben Funktionen zur Verfügung wie mit den OAuth1-APIs.
Abonnement-, V1- und V2-Endpunkte werden unter OAuth2 weiterhin unterstützt.
Weitere Informationen über die Konvertierung und ihre Auswirkungen finden Sie auf der Hilfeseite Anweisungen für OAuth1 zu OAuth2 oder in den Konvertierungsanweisungen .
Die Server-API besteht aus 5 APIs:
Abonnement-API : Endpunkte für die Interaktion von Benutzern mit Abonnements, Workflows und Zeitplänen (Aufträge).
Benutzer-V2-API : Endpunkte für Benutzer zur Interaktion mit Anmeldedaten, Eingabedateien und Zeitplänen (Jobs).
Admin-V1-API : Endpunkte für Administratoren, um Ressourcen von der Admin-Oberfläche abzurufen.
Admin-V2-API : Version 2 der Endpunkte für Administratoren, um Ressourcen von der Admin-Oberfläche abzurufen.
Admin-V3-API : Version 3 der Endpunkte. Diese Version verwendet OAuth2.
Anmerkung
Zusätzlich zur Erweiterung um neue Funktionen mit V3-API-Endpunkten haben wir auch unsere V1-, Abonnement- und V2-Endpunkte für die Verwendung mit OAuth2 zur Verfügung gestellt. Die gleichen Endpunkte, die Sie in der Vergangenheit verwendet haben, stehen nun für OAuth2 unter einer neuen Basisadresse zur Verfügung.
Die Web-API-Adresse kann nur für V1, V2 und V3 mithilfe von OAuth2 eingerichtet werden. Für die API-Dokumentation von V1 und V2 mit OAuth 1 lautet die Adresse http://{ServerHostname}/gallery/api-docs/ .
Auf Referenzdokumente der Server-API zugreifen
Die vollständige Referenzdokumentation für alle Server-API-Endpunkte ist in Swagger verfügbar.
In der Server-Benutzeroberfläche gibt es zwei Stellen, an denen Sie auf die Server-API-Referenzdokumentation zugreifen können.
Wählen Sie das Fragezeichen-Symbol in der oberen Symbolleiste und anschließend API-Dokumentation .
Wählen Sie Ihren Benutzernamen und dann Mein Profil > Schlüssel . Neben den API-Schlüsseln finden Sie Links zur API-Dokumentation.
Sie können auch über die folgende URL auf die API-Referenzdokumentation für die Server-API zugreifen: http(s)://serverhostname.domain/webapi/swagger
Sich für die Referenzdokumente der Server-API authentifizieren
Die Server-API-Dokumente sind interaktiv, sodass Sie Parameter eingeben und die Antworten anzeigen können. Um die Interaktivität nutzen zu können, müssen Sie sich authentifizieren. Folgen Sie dazu diesen Schritten:
Wählen Sie in der Server-Benutzeroberfläche Ihren Benutzernamen und anschließend Mein Profil > Schlüssel . Kopieren Sie die API-Schlüssel für die API, bei der Sie sich authentifizieren möchten, und fügen Sie sie in die Felder API-Schlüssel und Freigegebene Geheimnisse ein. Die Schlüssel werden als Gespeichert angezeigt.
Wählen Sie den Aufruf, den Sie ausführen möchten. Füllen Sie die Parameter aus und wählen Sie Testen .
API-Schlüssel und API-Zugriff
Administratoren (Server-Admins) müssen Benutzer:innen den Zugriff auf die API erlauben. Weitere Informationen finden Sie unter Benutzerzugriff auf die Server-API erlauben . Sobald Sie den Benutzerzugriff auf die API gewährt haben, können Benutzer ihre API-Schlüssel auf der Registerkarte Schlüssel der Seite Mein Profil finden. Um auf Ihre API-Schlüssel zuzugreifen, wählen Sie Ihren Benutzernamen und dann Mein Profil > Schlüssel aus.
Benutzer:innen mit der Rolle „Administrator“ können mit den Schlüsseln für den API-Zugriff auf alle APIs zugreifen, einschließlich der Abonnement-API, der Benutzer-V2-API, der V1-Admin-V1-API, der V2-Admin-V2-API und der V3-API.
Alle Benutzer:innen ohne die Rolle „Administrator“ können die Schlüssel für den API-Zugriff verwenden, um auf die Abonnement-API und die Benutzer-V2-API zuzugreifen.
Alle Benutzer können die privaten Studio-API- Schlüssel verwenden, um auf die Subscription-API zuzugreifen.
API-Endpunkte erstellen
Um einen API-Endpunkt zu erstellen, verwenden Sie dieses Schema: <hostname>/webapi/
Authentifizierung
Weitere Informationen finden Sie im Artikel Konfigurierung und Autorisierung der Server-API .
API-Endpunkte und -Parameter
In diesem Abschnitt finden Sie weitere Informationen zu den folgenden Endpunkten:
Server verfolgt Änderungen an diesen System-Entitäten:
AppInfo (Workflow)
Sammlung
Anmeldedaten
Abonnement
Benutzer
UserGroup
Protokollierte Ereignisse über die Server-API abrufen
Alle Aktualisierungen dieser Entitäten lösen die Erstellung eines AuditEvent-Datensatzes aus. Sie können diese Einträge über einen öffentlichen Admin-API-Endpunkt zurückgeben.
Endpunkt
Der Endpunkt für AuditEvents ist
GET /admin/v1/auditlog/
Erforderliche Abfrageparameter
entity
: (Zeichenfolge) die Überwachungsprotokoll-Entität, die Sie abfragen möchten.page
: (Ganzzahl) die Seite, die Sie zurückgeben möchten.pageSize
: (Ganzzahl) die Anzahl der Datensätze, die Sie auf jeder Seite zurückgeben möchten.
Die Antwort besteht aus einem Array von Einträgen der Überwachungsereignisse:
[ { "id": "", "entity": "", "entityId": "", "userId": "", "timestamp": "Date", "event": "", "oldValues": "", "newValues": "" } ]
Die zurückgegebenen Eigenschaften sind wie folgt definiert:
id
: die Überwachungsereignis-ID.entity
: der Name der Entität.entityId
: die Entitäts-ID der Entität.userId
: die ID des Benutzers, der die Entität geändert hat.timestamp
: Datum und Uhrzeit der Datensatzerstellung für das Überwachungsereignis.event
: das aufgetretene Ereignis (Einfügen, Aktualisieren, Löschen).oldValues
: die Werte der aktualisierten Eigenschaften vor der Aktualisierung.newValues
: die Werte der aktualisierten Eigenschaften nach der Aktualisierung.
Um Workflows, die das
Dateiauswahl-Tool
verwenden, über die API auszuführen, verwenden Sie den Endpunkt
/user/v2/inputfiles
zum Hochladen der Datei.
Beginnen Sie mit einer POST-Anfrage im Format multipart/form-data an den Endpunkt
/user/v2/inputfiles
, um eine temporäre Datei zu veröffentlichen. Der Name des erforderlichen form-data-Abschnitts lautetinputFile
.curl --location --request POST 'http:{yourhostname}/api/user/v2/inputfiles/' \ --form 'inputFile=@/file/path/filename.csv'
Senden Sie als Nächstes eine POST-Anfrage an den Endpunkt
/user/v2/workflows/{appId}/jobs/
.Fügen Sie dann den
Namen
des Dateiauswahl-Tools in das Frageobjekt ein. Wenn Sie sich bei dem Namen des Dateiauswahl-Tools nicht sicher sind, verwenden Sie den Endpunkt/v1/workflows/{appId}/questions
, um den Namen des Dateiauswahl-Tools zu erhalten.Der
value
ist die Referenz-ID, die der Aufruf Ihrer Eingabedatei in der Antwort zurückgegeben hat.
curl --location --request POST 'http:{yourhostname}/api/user/v2/workflows/{appId}/jobs' \ --header 'Content-Type: text/plain' \ --header 'Authorization: OAuth oauth_consumer_key="{consumer key}", oauth_signature_method="HMAC-SHA1", oauth_timestamp="{timestamp}", oauth_nonce="{nonce}", oauth_signature="{signature}"' \ --data-raw '{ "questions": [ { "name": "File Browse", "value": "{reference ID}" } ] "priority": "Low" }'
Verwenden Sie den
migratable
Endpunkt, um Workflows über Server-Umgebungen hinweg zu migrieren. Damit können Sie Workflow-Bereitstellungen während der Entwicklungs- und Testphase verwalten.
Zunächst müssen Sie Workflows für die Migration aktivieren . Nachdem Sie Workflows für die Migration markiert haben, befolgen Sie die folgenden Schritte, um sie aus der Quellumgebung in das entsprechende Abonnement (Studio) der Zielumgebung zu veröffentlichen.
1. Schritt: Eine Liste von Workflows abrufen, die für die Migration bereit sind
Als Nächstes rufen Sie mit dem folgenden Endpunkt eine Liste von Workflows ab, die für die Migration bereit sind:
Umgebung: Quelle
Methode: GET
Endpunkt:
api/admin/v1/workflows/migratable/?subscriptionIds={subscriptionIds}/
Fügen Sie eine kommagetrennte Liste von
subscriptionIds
als Abfrageparameter ein. Abonnement-IDs kennzeichnen ein bestimmtes Studio.
Die Rückgabe ist eine Reihe von Workflows, die als bereit für die Migration unter dem angegebenen Abonnement (Studio) markiert sind. Wenn Sie keine
subscriptionsIds
bereitstellen, enthält die Rückgabe alle Workflows, die als bereit für die Migration markiert sind. Die Rückgabe enthält drei Eigenschaften:
appId
, die aktuell veröffentlichte
revisionId
und die
subscriptionID
, zu der der Workflow gehört.
2. Schritt: Workflows aus der Quellumgebung herunterladen
Der folgende Endpunkt lädt den Workflow als YXZP-Datei herunter.
Umgebung: Quelle
Methode: GET
Endpunkt:
api/admin/v1/{appID}/package/
Fügen Sie eine
appID
als Pfadparameter ein. Die Rückgabe erfolgt als Download des gesamten Workflows als Paket.
3. Schritt: Workflows in der Zielumgebung veröffentlichen
Der folgende Endpunkt veröffentlicht den heruntergeladenen Workflow in der Zielumgebung.
Umgebung: Ziel
Methode: POST
Endpunkt:
api/admin/v1/workflows/
Parameter | |||
---|---|---|---|
Parameter | Beschreibung | Typ | Erforderlich |
| Der Dateiname des neuen Workflows. | Zeichenfolge | True (wahr) |
| Der neue Workflow-Name. | Zeichenfolge | True (wahr) |
| Der Besitzer des migrierten Workflows. Die E-Mail-Adresse muss in der Zielumgebung vorhanden sein. | Zeichenfolge | True (wahr) |
| Flag zum Validieren des Workflows bei der Migration in die Zielumgebung. | Boolesch | True (wahr) |
| Flag zum Setzen des Workflows auf „öffentlich“; wird in der Zielumgebung unter „Gallery meines Unternehmens“ angezeigt. | Boolesch | True (wahr) |
| Dies ist die appId der Quellumgebung des zu migrierenden Workflows. Wenn ein Workflow mit derselben sourceId vorhanden ist, wird dieser Workflow in der Zielumgebung ersetzt. Andernfalls wird ein neuer Workflow generiert. (Senden Sie eine leere Zeichenfolge, wenn Sie keine appID angeben möchten.) | Zeichenfolge | True (wahr) |
| Fügen Sie dem Workflow einen Worker-Tag hinzu, damit ein bestimmter Worker den Workflow ausführt. (Senden Sie eine leere Zeichenfolge, wenn Sie keinen Worker festlegen möchten.) | Zeichenfolge | True (wahr) |
| Flag zum Definieren des Workflows als für andere Benutzer in der Zielumgebung zum Herunterladen verfügbar. | Boolesch | True (wahr) |
(Optional) Schritt 4. Workflow-Migrationseinstellungen in der Quellumgebung zurücksetzen
Wenn Sie möchten, können Sie den
migratable
Endpunkt verwenden, um die Einstellung
Dieser Workflow ist bereit für die Migration
eines Workflows in der Quellumgebung nach der Workflow-Migration in der Zielumgebung wieder auf
Nein
zu setzen.
Umgebung: Quelle
Methode: PUT
Endpunkt:
api/admin/v1/workflows/migratable/{appID}/
Weitere Informationen zu den Endpunkten und Parametern der Server-API V3 finden Sie auf der Hilfeseite Alteryx Server-API V3 .