API-Übersicht

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

The Web API address can be set up in System Settings.

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:

Überwachungsprotokolle (Auditlogs): Endpunkt

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.

Endpunkt „inputfiles“

Um Workflows, die das Dateiauswahl-Tool verwenden, über die API auszuführen, verwenden Sie den Endpunkt /user/v2/inputfiles zum Hochladen der Datei. Dateiauswahl-Tool

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 lautet inputFile.
```
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"
}'

Endpunkt „migratable“

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
`file`	Der Dateiname des neuen Workflows.	Zeichenfolge	True (wahr)
`name`	Der neue Workflow-Name.	Zeichenfolge	True (wahr)
`owner`	Der Besitzer des migrierten Workflows. Die E-Mail-Adresse muss in der Zielumgebung vorhanden sein.	Zeichenfolge	True (wahr)
`validate`	Flag zum Validieren des Workflows bei der Migration in die Zielumgebung.	Boolesch	True (wahr)
`isPublic`	Flag zum Setzen des Workflows auf „öffentlich“; wird in der Zielumgebung unter „Gallery meines Unternehmens“ angezeigt.	Boolesch	True (wahr)
`sourceId`	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)
`workerTag`	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)
`canDownload`	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 .

In diesem Abschnitt: