REST API

Durch die Verwendung der Beekeeper-API kannst Du eine große Anzahl Nutzer gleichzeitig synchronisieren.

In unserem Developer Portal findest Du Informationen zur Strukturierung und Authentifizierung von Anfragen.

Wie bei einem regulären CSV/Excel-Import oder beim Synchronisieren per FTP erstellt dieser Endpunkt einen Import, der im Admin-Bereich unter Nutzer > Importe angezeigt wird.

Nutzer werden als mehrteilige Datei im JSON-Format an den Server gesendet (siehe unten). Sie werden anschließend asynchron importiert.

Dateistruktur

Der Endpunkt für gleichzeitige Importe akzeptiert eine Datei, die in jeder Zeile ein JSON-Nutzerobjekt enthält. Jedes Nutzerobjekt ist wie im folgenden Code-Block strukturiert. Beachte, dass die Struktur des Objekts „user_data“ mit der des Endpunkts /users übereinstimmt.

Nutzerinhalt:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": []
}

Dateiinhalt:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": []}
...

Nutzer werden anhand des Werts in „id_field“ identifiziert — nach Wahl entweder per „name“, „email“ oder „tenantuserid“ (die Bezeichnungen sind unten erklärt). Dieses Feld muss im Objekt „user_data“ vorhanden sein.

Wenn die Nutzer aufgrund des angegebenen Feldes id_field nicht abgeglichen werden können, erfolgt dies entsprechend der Liste id_field_fallbacks. Für die Liste id_field_fallbacks können dieselben Werte (name, email, tenantuserid) verwendet werden. Alternativ kann die Liste leer gelassen werden.

Die folgende cURL zeigt die JSON-Nutzerobjekte zum Erstellen, Aktualisieren, Sperren und Löschen, dabei wird wie zuvor der Nutzername Max Mustermann verwendet:

curl -X POST -H "Authorization: Token <access_key>" \
-H "Content-Type: multipart/form-data; boundary=3d1a8e334ce84031bdce8eb049467620" \
-d '--3d1a8e334ce84031bdce8eb049467620
Content-Disposition: form-data; name="file"; filename="user_data.json"
Content-Type: application/json

{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "email": "max_mustermann@example.com", "custom_fields": [{"key": "firstname", "value": "Max"}, {"key": "lastname", "value": "Mustermann"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann", "tenantuserid": "max_1", "custom_fields": [{"key": "firstname", "value": "Maxine"}]}}
{"type": "update", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_musterman", "suspended":true}}
{"type": "delete", "options": {"id_field": "name", "id_field_fallbacks": []}, "user_data": {"name": "max_mustermann"}}

--3d1a8e334ce84031bdce8eb049467620--
' 'https://unternehmen.beekeeper.io/api/2/users/force-import'

So erstellst/aktualisierst Du Nutzer:

Zum Erstellen oder Aktualisieren eines Nutzers stelle den Typ auf „update“ ein. Wenn der Nutzer nicht vorhanden ist, wird er automatisch erstellt.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "email": "max_mustermann@example.com",
    "suspended": false,
    "custom_fields": [
      {
        "key": "firstname",
        "value": "Max"
      },
      {
        "key": "lastname",
        "value": "Mustermann"
      },
      {
        "key": "position",
        "value": "IT Support"
      },
    ]
  },
  "groups": [
    { "name": "Honeybees" }
  ]
}

So sperrst Du Nutzer:

Füge wie oben im JSON-Nutzerobjekt das Feld „suspended=true“ hinzu.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
    "suspended": true
  }
}

So löschst Du Nutzer:

Lege den Typ auf „delete“ fest. Der Nutzer wird dann gelöscht.

{
  "type": "delete",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  }
}

So fügst Du Nutzer zu Gruppen hinzu:

Lege den Typ auf „update“ fest und führe alle Gruppennamen auf, denen der Nutzer angehören soll.

Um einen Nutzer aus einer Gruppe zu entfernen, entferne ihn einfach aus der Liste. Die Gruppenmitgliedschaften werden jedes Mal überschrieben.

{
  "type": "update",
  "options": {
    "id_field": "name"
  }, 
  "user_data": {
    "name": "max_mustermann",
  },
  "groups": [
   { "name" : "Honeybees" },
   { "name": "Bumblebees" }
  ]
}

Standorte

Wenn euer Produkt Standorte enthält, werden eure Nutzer dem Standardstandort zugeordnet. Du kannst sie aber auch anderen Standorten zuordnen. Wie bereits erwähnt, im Nutzerinhalt und Dateiinhalt. Die Werte der Standorte werden wie folgt addiert:

Nutzerinhalt:

{
  "type": "update|delete",
  "options": {
    "id_field": "name|email|tenantuserid", 
    "id_field_fallbacks": [
      "name|email|tenantuserid"
    ]
  }, 
  "user_data": {},
  "groups": [],
  "locations": []
}

Dateiinhalt:

{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
{ "type": "update|delete", "options": { "id_field": "name|email|tenantuserid", "id_field_fallbacks": [ "name|email|tenantuserid" ] }, "user_data": {}, "groups": [], "locations": []}
...

So fügst Du Nutzer zu Standorte hinzu:

Lege den Typ auf „update“ fest und führe alle Standortnamen auf, denen der Nutzer angehören soll.

Standardmässig sind alle Nutzer zunächst dem Standardstandorte zugeordnet. Ein Nutzer kann zu mehreren Standorten gehören.

{
  "type": "update",
  "options": {
  "id_field": "name"
 },
  "user_data": {
  "name": "max_mustermann",
 },
  "locations": [
   {"unique_name": "Asia"},
   {"unique_name": "America"}
 ]
}