Kontext dieses Dokuments: Die Flip Sync-API für Benutzer und Channels

Die Spezifikationen zum Lesen von Zuständen und Fehlern asynchroner Anfragen findest du unter dem folgenden Link.

Flip API-Dokumentation

Fehlermeldungen erhalten

Asynchrone Kommunikation wird für Aktivitäten verwendet, die mehr Verarbeitungszeit erfordern, was es unangebracht macht, aktiv auf das Ergebnis zu warten. Die Kommunikation verläuft dann so, dass nach dem Herstellen einer Verbindung mit dem Server und dem Senden der Daten der Server die Anfrage validiert (mit dem Hinweis, dass hier möglicherweise immer noch synchron mit HTTP 400 Bad Request) and geantwortet wird) und mit HTTP 202 Accepted antwortet. Zu diesem Zeitpunkt wurde die Anfrage intern zur weiteren Verarbeitung übergeben, und die aktuelle Verbindung wurde beendet.

Um Fehler zu verfolgen, die asynchron auftreten, können API-Aufrufe durch "Namen" oder, wie sie in den JSON-Objekten genannt werden, request_context gruppiert werden. Dies ermöglicht es dir, eine große Aufgabe über mehrere Anfragen hinweg auszuführen und dennoch eine Aggregation aller Statusinformationen und zugehörigen Fehler abzurufen. Ein Kontext könnte zum Beispiel "user_migration_3.8.2022" sein. Diese Funktion ist optional. Wenn sie nicht angegeben wird, wird der request_context auf einen eindeutigen zufälligen Wert gesetzt, der später verwendet werden kann, um auf diese einzelne Anfrage zuzugreifen.

Bitte beachte, dass du, wenn du denselben Anfragekontext mehreren Anfragen zuweist, diese nicht mehr einzeln abrufen kannst, da alle Fehler mit diesem Anfragekontext angezeigt werden.

Nachdem deine Anfrage erfolgreich akzeptiert wurde, möchtest du wahrscheinlich deren Verarbeitungsstatus bis zum Abschluss verfolgen. Unser Endpunkt api/external/v1/requests/{request_context} bietet diese Funktionalität. Ersetze request_context durch den Wert, den du in der Antwort auf die Anfrage zur Benutzer- und Gruppen-Sync-API erhalten hast. Die Antwort enthält die Anzahl der bereits für deine Anfrage verarbeiteten Arbeitselemente und wie viele davon Fehler verursacht haben. Sieh dir die API-Spezifikation für detailliertere Informationen an.

{
    batch_size: 100,
    batch_items_completed: 42,
    errors: 2
}

Falls während der Verarbeitung deiner Anfrage Fehler auftreten, stellen wir den Endpunkt api/external/v1/requests/{request_context}/error zur Verfügung, um detaillierte Informationen zu allen Fehlern zu erhalten. Ersetze request_context durch den Wert, den du in der Antwort auf die Anfrage zur Benutzer- und Gruppen-Sync-API erhalten hast. Dieser Endpunkt unterstützt die Paginierung der Fehlerliste, sodass deine Antwort eine (möglicherweise Teilmenge) Liste aller Fehler mit dem Namenerrors und ein Cursor-Objekt zum Abrufen der nächsten Seite, falls vorhanden, namens next_cursor enthält. Sieh dir die API-Spezifikation für detailliertere Informationen an.

{
    "errors": [
        {
            "error_cause": "External Id is blank",
            "error_name": "validation",
            "item": {
                "user_external_id": "7170346245"
            },
            "reported_at": "2022-07-18T08:05:48.975425Z"
        }
    ],
    "next_cursor": {
        "after": "rO0A.......NKUA==",
        "has_more": false
    }
}

Überblick über mögliche Fehler

Fehler, die beim Erstellen, Aktualisieren oder Löschen von Gruppen und Benutzern auftreten, werden gesammelt. Da diese Prozesse einige Zeit in Anspruch nehmen und asynchron abgewickelt werden, können sie nicht direkt als HTTP-Fehlercodes zurückgegeben werden. Das bedeutet, dass ein Fehler auftritt, nachdem der ursprüngliche HTTP-Aufruf beendet wurde.

Die verschiedenen Fehler, die im JSON möglich sind, sind:

Beispiel: external id blank

{
  "request_context": "my-context",
  "users": [
    {
      "system_role": "USER",
      "external_id": "my-external-id",
      "username": "username",
      "first_name": "firstname",
      "last_name": "lastname",
      "tags": [
        {
          "key": "memberOf",
          "value": ""
        }
      ]
    }
  ]
}

Beispiel: password policy

{
  "request_context": "my-context",
  "users": [
    {
      "system_role": "USER",
      "external_id": "my-external-id",
      "username": "username",
      "first_name": "firstname",
      "last_name": "lastname",
      "login": {
        "password": {
          "password": "tooshort",
          "temporary": true
        }
      }
    }
  ]
}

Beispiel: password history

{
  "request_context": "my-context",
  "users": [
    {
      "system_role": "USER",
      "external_id": "my-external-id",
      "username": "username",
      "first_name": "firstname",
      "last_name": "lastname",
      "login": {
        "password": {
          "password": "VerY-GoOd-PassW%rd!",
          "temporary": true
        }
      }
    }
  ]
}

Vollständiges Beispiel für einen erfolgreichen und einen fehlgeschlagenen Fall einer Anfrage zur Erstellung eines Benutzers

Das Beispiel zeigt die gesamte Erstellung eines Benutzers, aber die Schritte sind für alle asynchronen Operationen gleich.

Anfrage zur Erstellung eines Benutzers (erfolgreicher Fall)

POST /api/external/v2/sync/users HTTP/1.1
Accept: application/json
Authorization: Bearer eyJh...
Content-Type: application/json
Host: flipapp.de

{
    "request_context": "my-context",
    "users": [
        {
            "confirm_terms_and_conditions": "ASK_ON_NEXT_LOGIN",
            "external_id": "6fe424c308",
            "first_name": "40d5fb76",
            "last_name": "40d5fb76",
            "login": {
                "password": {
                    "password": "Password",
                    "temporary": true
                }
            },
            "system_role": "USER",
            "username": "40d5fb76"
        }
    ]
}

Antwort:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "request_context": "my-context"
}

Überprüfung möglicher Fehler (erfolgreicher Fall)

GET /api/external/v1/requests/my-context/errors HTTP/1.1
Accept: application/json
Authorization: Bearer eyJh...
Connection: keep-alive
Host: flipapp.de

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "errors": [],
    "next_cursor": {
        "has_more": false
    }
}

In diesem Fall gab es keine Fehler, daher ist die Liste leer.

Anfrage zur Erstellung eines Benutzers (fehlgeschlagener Fall)

POST /api/external/v2/sync/users HTTP/1.1
Accept: application/json
Authorization: Bearer eyJh...
Content-Type: application/json
Host: flipapp.de

{
    "request_context": "my-context",
    "users": [
        {
            "external_id": "a3ef74bdde",
            "first_name": "firstname",
            "last_name": "lastname",
            "system_role": "USER",
            "tags": [
                {
                    "key": "memberOf",
                    "value": ""
                }
            ],
            "username": "ea0298c5"
        }
    ]
}

Antwort:

HTTP/1.1 202 Accepted
Content-Type: application/json

{
    "request_context": "my-context"
}

Überprüfung möglicher Fehler (fehlgeschlagener Fall)

GET /api/external/v1/requests/my-context/errors HTTP/1.1
Accept: application/json
Authorization: Bearer eyJh...
Host: flipapp.de

Antwort:

HTTP/1.1 200 OK
Content-Type: application/json

{
    "errors": [
        {
            "error_cause": "External Id is blank",
            "error_name": "validation",
            "item": {
                "user_external_id": "a3ef74bdde"
            },
            "reported_at": "2022-08-08T13:40:19.218601Z"
        }
    ],
    "next_cursor": {
        "after": "rO0...",
        "has_more": false
    }
}

Es gibt einen Fehler in der Fehlerliste.