Zu Content springen
Deutsch
  • Es gibt keine Vorschläge, da das Suchfeld leer ist.

Die big API nutzen: Zugang einrichten und Daten abfragen

API Key erstellen, anmelden und Elemente, Attribute und Versionen lesen oder ändern

API Key erstellen, anmelden und Elemente, Attribute und Versionen lesen oder ändern

Über die REST-API von big lesen Sie Projektdaten aus anderen Anwendungen aus und ändern Attributwerte, ohne die Oberfläche von big zu öffnen. In dieser Anleitung erstellen Sie einen API Key, ermitteln die benötigten Kennungen und lernen die verfügbaren Abfragen kennen.

API Key erstellen

Jeder Benutzer kann für sich selbst einen API-Zugang anlegen.

  1. Klicken Sie oben rechts auf Ihr Benutzersymbol und wählen Sie Mein Account.
  2. Wechseln Sie zum Reiter API-Zugang.
  3. Klicken Sie auf das Plus-Symbol, um einen neuen Zugang anzulegen.
  4. big erzeugt einen API Key und ein API Secret. Kopieren Sie das Secret sofort und bewahren Sie es sicher auf.

Wichtig: Das API Secret wird nur in diesem Moment angezeigt. Nach dem Schließen des Fensters lässt es sich nicht mehr abrufen. Bei Verlust erstellen Sie einfach einen neuen Zugang.

Der API Key bleibt in der Übersicht sichtbar und dient bei der Anmeldung als Client ID. Nicht mehr benötigte Zugänge entfernen Sie über das Papierkorb-Symbol in der jeweiligen Zeile.

Benötigte Angaben ermitteln

Für die Abfragen benötigen Sie neben API Key und Secret folgende Kennungen aus big:

Angabe

Bedeutung

Wo Sie sie finden

Domain

Name Ihrer big-Instanz, Teil der Adresse, z. B. demo-de in demo-de.build-big.ch

In der Adresszeile Ihres Browsers, wenn Sie big geöffnet haben

Projekt-ID

Nummer des Projekts

Auf der Projektkachel in der Projektübersicht, neben dem Rautezeichen (#)

Element-ID

Nummer eines Elements, z. B. 25

Unter Elemente & Attribute, neben dem Elementnamen nach dem Rautezeichen (#)

Alle Adressen der API beginnen mit https://[Domain].build-big.ch.

An der API anmelden

Vor jeder Abfrage fordern Sie ein Zugriffstoken an:

  1. Senden Sie eine POST-Anfrage an /auth/login/token.
  2. Übergeben Sie im Formularformat die Werte client_id (Ihr API Key), client_secret (Ihr API Secret) und grant_type mit dem Wert client_credentials.
  3. Die Antwort enthält ein access_token.

Bei allen weiteren Anfragen senden Sie dieses Token im Header Authorization als Bearer [Token]. Für projektbezogene Abfragen ergänzen Sie den Header X-PROJECT-ID mit Ihrer Projekt-ID.

Verfügbare Abfragen

Die folgenden Endpunkte hängen Sie an die Basisadresse Ihrer Domain an. Platzhalter in eckigen Klammern ersetzen Sie durch die jeweilige ID.

Aktion

Methode

Endpunkt

Versionen abrufen

GET

/api/entity/versions

Alle Elemente mit ihren Attributen abrufen

GET

/api/entity/elements

Typen eines Elements abrufen

GET

/api/entity/[Element-ID]/types

Alle Instanzen eines Elements abrufen

GET

/api/entity/[Element-ID]

Instanzen nach Attributwert filtern

GET

/api/entity/[Element-ID]?key=[Attribut]&value=[Wert]

Eine einzelne Instanz abrufen

GET

/api/entity/instance/[Instanz-ID], optional mit ?version_id=[Versions-ID]

Änderungen gegenüber dem aktuellen Stand abrufen

GET

/api/entity/[Element-ID]/delta/[Versions-ID]

Änderungen zwischen zwei Versionen abrufen

GET

/api/entity/[Element-ID]/delta/[Versions-ID]/[spätere Versions-ID]

Neuen Typ anlegen

POST

/api/entity/[Element-ID]/type

Neue Instanz anlegen

POST

/api/entity/[Element-ID]

Attributwerte einer Instanz ändern

PUT

/api/entity/[Element-ID]/[Instanz-ID]

Beispiel: Mit key=Geschoss und value=1. Obergeschoss erhalten Sie alle Instanzen des Elements, deren Attribut „Geschoss“ den Wert „1. Obergeschoss“ hat.

Bei Änderungsabfragen (delta) können Sie zusätzlich angeben:

  • status: welche Änderungen geliefert werden, möglich sind INSERTED, DELETED, UPDATED und UNMODIFIED. Ohne Angabe werden neue, gelöschte und geänderte Instanzen geliefert.
  • full: mit true erhalten Sie die vollständigen Instanzdaten statt nur der Änderungen.

Beim Anlegen von Typen und Instanzen übergeben Sie die Daten im JSON-Format, also den Namen bzw. den Typnamen und die gewünschten Attributwerte.

Die Abfragen funktionieren mit jedem Werkzeug oder jeder Programmiersprache, die REST-Anfragen unterstützt, zum Beispiel Visual Studio Code mit der Erweiterung REST Client.

Berechtigungen

Welche Abfragen und Änderungen möglich sind, hängt vom Rollenrecht des Benutzers ab, dem der API Key gehört. Für schreibenden Zugriff benötigen Sie ein passendes Rollenrecht und müssen der Disziplin zugewiesen sein, zu der das Attribut gehört.

Häufige Fragen

Ich habe das API Secret nicht kopiert. Kann ich es erneut anzeigen?

Nein. Das Secret wird nur beim Erstellen angezeigt. Löschen Sie den Zugang und legen Sie einen neuen an.

Warum schlägt eine Abfrage oder Änderung fehl, obwohl die Anmeldung funktioniert?

Vermutlich reicht Ihr Rollenrecht nicht aus oder Sie sind der Disziplin des Attributs nicht zugewiesen. Ein anderes Rollenrecht kann Ihr Ansprechpartner bei Kaulquappe einrichten.

Wo finde ich die Element-ID?

Unter Elemente & Attribute steht sie neben dem Elementnamen nach dem Rautezeichen.

An wen wende ich mich bei weiteren Fragen?

Schreiben Sie uns gerne eine E-Mail an support@build-big.ch.