Skip to main content

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

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.

  1. Wählen Sie das Fragezeichen-Symbol in der oberen Symbolleiste und anschließend API-Dokumentation .

    Thumbnail
  2. 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:

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

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

API keys are located under My Profile Keys.

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.File Browse Tool Icon Dateiauswahl-Tool

  1. 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' 
  2. Senden Sie als Nächstes eine POST-Anfrage an den Endpunkt /user/v2/workflows/{appId}/jobs/ .

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

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

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 .