Sync-API: Häufige Probleme

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

In enger Zusammenarbeit mit unseren Kunden haben wir häufige Muster bei der Nutzung der Sync-API festgestellt, die zu Hürden und Fehlern führen.

Um das Senden von Daten so einfach wie möglich zu machen, haben wir fünf häufige Hürden oder Fehler zusammengestellt, denen unsere Kunden während der technischen Integration begegnen. Dieser Leitfaden soll dir helfen, diese typischen Probleme schnell zu lösen, damit du den Integrationsprozess zügig abschließen kannst (bitte beachte, dass in den folgenden JSON-Beispielen nur die erforderlichen Felder vorhanden sind).

Wichtig zu wissen

Da die Sync-API asynchron für alle POST-Anfragen arbeitet, die du von unserem Server erhältst, lautet die Antwort HTTP 202 Accepted (es sei denn, es tritt ein Fehler bei der Validierung der Anforderungs-URL und des gesendeten JSON auf. In diesem Fall lautet die Antwort HTTP 400 Bad Request).
Um asynchrone Fehler zu verfolgen, hat jede API-Anfrage einenrequest_context, der die Anfrage identifiziert. Du kannst einen Wert für den request_context festlegen oder ihn unbestimmt lassen (in diesem Fall wird ihm ein zufälliger eindeutiger Wert zugewiesen).
Um Informationen über den Status deiner Anfrage zu erhalten, kannst du den request_context als Pfadparameter für den Endpunkt /api/external/v1/requests/{request_context} angeben. Wenn ein Fehler auftritt, kannst du Informationen über den Fehler erhalten, indem du eine Anfrage an den Endpunkt /api/external/v1/requests/{request_context}/errors sendest.
Die Kennungen eines Benutzers sind username und external_id. Die Kennungen eines Kanals sind group_id (interne ID, die automatisch vom Flip-Backend erstellt wird) und external_id.
Die alten Flipgroups werden jetzt als channels bezeichnet. Um breaking changes in der API zu vermeiden, verwenden wir weiterhin das Wort group(s) für alle Endpunkt- und Parameternamen.

Fehler bei der Passwort-Richtlinie

Jedes Kundenkonto bei Flip hat eine Standard-Passwort-Richtlinie:

Das Passwort darf nicht mit den letzten drei Passwörtern eines Benutzers übereinstimmen, und
das Passwort sollte eine Mindestlänge von 8 Zeichen haben.
das Passwort darf nicht dem Benutzernamen entsprechen.

(Unsere Kunden können die Passwort-Richtlinie bei Flip wählen. Frage die Verantwortlichen für das "Flip"-Projekt deines Unternehmens nach der spezifischen Passwort-Richtlinie, die deine Kollegen gewählt haben.)

Das Problem

Jedes Mal, wenn du ein Passwort sendest, das nicht der Richtlinie entspricht, tritt ein Fehler auf, und das Passwort wird nicht aktualisiert.

Angenommen, du hast die Standard-Passwort-Richtlinie:

Wenn du ein Passwort sendest, das mit den letzten drei Passwörtern eines Benutzers übereinstimmt, erhältst du den folgenden Fehler:

{
    "errors": [
        {
            "error_cause": "Invalid password history: Invalid password: must not be equal to any of last 3 passwords.",
            "error_name": "identity_provider",
            "item": {
                "user_external_id": "7170346245"
            },
            "reported_at": "2022-21-01T08:05:48.975425Z"
        }
    ],
    "next_cursor": {
        "after": "rO0A.......NKUA==",
        "has_more": false
    }
}

Wenn du ein Kennwort sendest, das nicht mit den acht Zeichen übereinstimmt, erhälst du die folgende Fehlermeldung:

{
  "errors": [
    {
      "error_name": "identity_provider",
      "error_cause": "Password policy not met: Invalid password: minimum length 8.",
      "reported_at": "2022-12-01T15:34:29.928182Z",
      "item": {
        "user_external_id": "yxcvasdf"
      }
    }
  ],
  "next_cursor": {
    "after": "rO0A....\\u003d",
    "has_more": false
  }
}

Die Lösung

Um das Problem zu lösen, empfehlen wir, den Ansatz zur Vergabe eines Passworts zu ändern:

Erstelle eine Logik zur Erstellung eines Anfangspassworts für denselben Benutzer und verwende diese Logik für alle Benutzer. Diese Logik kann einfach sein, wie z.B. das Passwort gleich dem Benutzernamen zu setzen (was wir nicht empfehlen), oder komplizierter, wie die Mitarbeiter-ID + Datum der Erstellung/Aktualisierung des Benutzers.
Jede Logik hat Vor- und Nachteile. Deshalb schlagen wir vor, das Passwort nur für den ersten Login des Benutzers zu senden und es als temporär festzulegen.

Erstellen oder Ändern der external_id von Benutzern und Kanälen

In der Regel werden die ersten Benutzer und Kanäle in Test- und Produktionssystemen manuell in der Flip-App erstellt. Die external_id ist die Kennung eines Objekts, die der Kunde festlegt und verwendet, um CRUD-Operationen mit der Sync-API durchzuführen.

Das Problem

Situationen:

Da Benutzer und Channels, die in der Flip-App erstellt wurden, keine external_id haben, kannst du sie nicht mit der Sync-API aktualisieren oder löschen, es sei denn, du weist ihnen eine zu.
Manchmal möchtest du vielleicht die external_id eines Benutzers oder eines Kanals ändern.

Du kannst eine external_id in beiden Situationen mit der Sync-API erstellen oder aktualisieren.

Die Lösung

Jeder Benutzer hat einen Benutzernamen und jeder Channel hat eine „interne ID“, eine UUID, die automatisch vom Flip-Backend festgelegt wird. Sowohl der Benutzername als auch die „interne ID“ sind Flip-Kennungen für die Objekte.

Du kannst beide verwenden, um das Objekt einer external_id zuzuordnen:

Verwende die Endpunkte /api/external/sync/v3/users oder /api/external/v1/sync/groups, um alle Benutzer oder alle Channels abzurufen.
Identifiziere den Benutzer oder Channel, den du aktualisieren oder löschen möchtest, und kopiere in die JSON-Datei den Wert des Schlüssels username (z.B. „test_user“) für Benutzer oder den Wert des Schlüssels name (z.B. „Test Channel“) und id (z.B. „306d…2d8f“) für die Channels.

Für Benutzer wähle eine external_id (z.B. „foo“) und sende folgendes JSON-Beispiel:

{
  "users": [
    {
      "external_id": "foo",
      "first_name": "Test",
      "last_name": "User",
      "system_role": "USER",
      "tags": [
      ],
      "username": "test_user"
    }
  ]
}

Für Channels wähle eine externe_id (z. B. "bar") und senden das folgende JSON-Beispiel:

{
  "groups": [
    {
      "external_id": "bar",
      "group_id": "306d...2d8f",
      "name": "Test_Channel"
    }
  ]
}

Jetzt hat der Benutzer oder der Kanal die gewünschte external_id.

group_id wird ignoriert, wenn die gesendete external_id bereits einem anderen Kanal zugeordnet ist

Wie du im vorherigen Kapitel sehen kannst, kannst du eine external_id einem Channel zuordnen, indem du die group_id sendest.

Es gibt jedoch einige Fälle, in denen die gesendete group_id ignoriert wird. Dies passiert, wenn du eine external_id sendest, die bereits einem Channelnamen zugeordnet ist. Unser Backend versteht dies als Versuch, Channeleigenschaften außer dem Namen und der external_id zu aktualisieren.

Der typische Anwendungsfall betrifft das Löschen von Channels. Um den Randfall der Wiederherstellung fälschlicherweise gelöschter Daten abzudecken, verwenden wir eine sogenannte „soft deletion“. Das bedeutet, dass Benutzer und Channels ohne Datenverlust (d.h. Chat-Inhalte, Kanalinhalte usw.) wiederhergestellt werden können. Dies kann jedoch dazu führen, dass ein Kanal zweimal vorhanden ist. Nach dem Löschen eines Kanals wurde ein neuer mit demselben Namen manuell in der App erstellt, und nun möchtest du diesem Kanal eine external_id zuweisen, indem du die group_id verwendest.

Das Problem

Betrachte diesen Anwendungsfall:

Du erstellst den folgenden Channel mit der Sync-API:

Name
group_id external_id

News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters
Nach einigen Tests entscheidest du, ihn zu löschen.
Dein Projektmanager erstellt einen neuen Kanal in der Flip-App, „News from the Headquarters“, um Informationen mit allen Hauptsitzmitarbeitern zu teilen.

Name group_id

News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002
Einige Informationen werden im Channel geteilt.
Du möchtest viele Benutzer zu diesem Channel mit der Sync-API hinzufügen. Um dies zu erreichen, musst du diesem Channel eine external_id zuweisen. Du sendest die folgende JSON-Datei, um den Channel einer external_id zuzuordnen:
```
{
  "groups": [
    {
      "external_id": "news_from_the_headquarters",
      "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002",
      "name": "News from the Headquarters"
    }
  ]
}
```
Dadurch wird die von Ihnen gesendete group_id ignoriert, da unser Backend Ihre Anfrage als Versuch versteht, den gelöschten Kanal zu reaktivieren, der bereits eine external_id hat. Folglich haben Sie jetzt zwei Kanäle mit demselben Namen:

Name group_id external_id

News from the Headquarters 4148b546-76fb-11ed-a1eb-0242ac120002

News from the Headquarters bfa5f3f1-8813-4900-b6c0-bedeef40e7a3 news_from_the_headquarters

Die Lösung

Befolge diese Schritte:
1. Ändere die external_id des abgerufenen Channels, indem du die folgende JSON-Datei sendest:
```
{
  "groups": [
    {
      "external_id": "false_id",
      "group_id": "bfa5f3f1-8813-4900-b6c0-bedeef40e7a3",
      "name": "News from the Headquarters"
    }
  ]
}
```
2. Lösche den Channel:
```
{
  "groups": [
    {
      "external_id": "false_id"
    }
  ]
}
```
3. Ordne dem in der Flip-App erstellten Channel die gewünschte external_id zu:
```
{
  "groups": [
    {
      "external_id": "news_from_the_headquarters",
      "group_id": "4148b546-76fb-11ed-a1eb-0242ac120002",
      "name": "News from the Headquarters"
    }
  ]
}
```
Jetzt haben Sie den richtigen Kanal mit der gewünschten external_id.

Federated identity '...' ist nicht für einen Mandanten konfiguriert

Das Problem

Ihr möchtet, dass sich der Benutzer mit Single Sign On (SSO) anmeldet. Um den Identitätsanbieter für den Benutzer einzurichten, sende eine POST-Anfrage an den Endpunkt /api/external/sync/v3/users mit dem Feld identity_provider:
```
{
  "users": [
    {
      "external_id": "foo",
      "first_name": "Test",
      "last_name": "User",
      "system_role": "USER",
      "tags": [
      ],
      "username": "test_user",
      "login": {
        "identity_provider": {
          "alias": "saml-azure",
          "user_id": "test_user",
          "username": "test_user"
        }
      }
    }
  ]
}
```
Über den Endpunkt /api/external/v1/requests/{request_context}/errors erhälst du den folgenden Fehler:
```
{
  "errors": [
    {
      "error_name": "validation",
      "error_cause": "Federated identity 'saml-azure' is not configured for tenant.",
      "reported_at": "2022-12-18T02:45:51.702973Z",
      "item": {
        "user_external_id": "foo"
      }
    }
  ],
  "next_cursor": {
    "after": "rO0N.......1u003d",
    "has_more": false
  }
}
```
Die Lösung

Der Fehler wird dadurch verursacht, dass für euer Firmenkonto kein Identitätsanbieter namens saml-azure eingerichtet ist.

Um das Problem zu lösen, musst du dich mit Flip in Verbindung setzen, damit ein Identitätsanbieter für Ihr Firmenkonto eingerichtet werden kann.

Es existiert kein Kanal mit der angegebenen ID

Das Problem

Wenn du die folgende POST-Anfrage an /api/external/v1/sync/groups mit einer group_id sendest, die nicht existiert:
```
{
  "groups": [
    {
      "external_id": "bar",
      "group_id": "0027....fe2d8f", // assume this id is false
      "name": "Test_Channel"
    }
  ]
}
```
Bekommst du den folgenden Fehler:
```
{
  "errors": [
    {
      "error_name": "not_found",
      "error_cause": "No group with group ID '0027.......fe2d8f' exists.",
      "reported_at": "2022-12-20T14:47:47.014606Z",
      "item": {
        "group_external_id": "foo"
      }
    }
  ],
  "next_cursor": {
    "after": "rO0A.......\\u003d",
    "has_more": false
  }
}
```
Die Lösung

Es gibt nur eine echte Lösung für das Problem, wenn du eine bestehende group_id sendest.

Wenn dieser Fehler auftritt, hat der Client normalerweise nicht die Absicht, einem Channel, der die group_id sendet, eine external_id zuzuweisen (siehe andere Fälle in diesem Artikel).

Stattdessen will der Client einen neuen Channel erstellen und nimmt an, dass eine group_id gesetzt werden soll. Die group_id ist eine interne ID, die nur vom Flip-Backend gesetzt wird, und ist nicht erforderlich, um einen Channel zu erstellen.

Sync-API: Häufige Probleme

Wichtig zu wissen

Fehler bei der Passwort-Richtlinie

Erstellen oder Ändern der external_id von Benutzern und Kanälen

group_id wird ignoriert, wenn die gesendete external_id bereits einem anderen Kanal zugeordnet ist

Federated identity '...' ist nicht für einen Mandanten konfiguriert

Es existiert kein Kanal mit der angegebenen ID

War dieser Beitrag hilfreich?

Kommentare

<%= previousTitle %>

<%= nextTitle %>

Inhalt des Artikels

<%= heading %>

<%= block.name %>

<%= heading %>

<% if (block.html_url) { %> <%= block.name %> <% } else { %> <%= block.name %> <% } %>

Du hast die Antwort auf deine Frage noch nicht gefunden?

Kategorien

Navigationsmenü öffnen/schließen

<%= category.name %>

Name	group_id	external_id
News from the Headquarters	4148b546-76fb-11ed-a1eb-0242ac120002
News from the Headquarters	bfa5f3f1-8813-4900-b6c0-bedeef40e7a3	news_from_the_headquarters