API BIMcollab Twin Schnellstart

API BIMcollab Twin Schnellstart

Dieses Dokument soll eine menschenfreundliche Schnellstartbeschreibung der BIMcollab Twin Public API bieten. Eine ausführliche Dokumentation über unsere API finden Sie unter https://api.demo-bimlink.nl/swagger. Um Zugang zu unserer API und der Dokumentation zu erhalten, benötigen Sie ein BIMcollab Twin Konto. Um die BIMcollab Twin Public API von Ihrer Anwendung aus nutzen zu können, benötigen Sie Client-Zugangsdaten und müssen Ihre Redirect-URL bei unserem Authentifizierungsserver weiß gelistet haben. Wenn Sie unsere API nutzen möchten, kontaktieren Sie uns bitte unter docsdevelopment@bimcollab.com. Alle Endpunkte auf dieser Seite verwenden zu Testzwecken die Domain unseres Demoservers (demo-bimlink.nl). Um echte Kundendaten abzufragen, verwenden Sie unseren Live-Server (bimlink.nl).

Schritt 1: Autorisierung

Jede Anfrage an die API muss mit einem Zugriffs-Token authentifiziert werden. In den meisten Fällen wird ein Zugriffs-Token mit Hilfe des OAUTH2-Autorisierungscode-Flusses erhalten. Grundsätzlich bedeutet dies, dass der Benutzer von Ihrer Anwendung auf die BIMcollab Twin-Anmeldeseite umgeleitet werden muss und nach erfolgreicher Autorisierung zurück zu Ihrer Anwendung geleitet wird. Mit dem erhaltenen Autorisierungs-Token kann dann ein Access-Token angefordert werden. Das Zugriffstoken kann dann zum "Authorization"-Header Ihrer Anfragen im Format hinzugefügt werden: "Bearer <accesstoken>". Token werden im JWT-Format bereitgestellt, so dass sie bei der Dekodierung (Base64) weitere Informationen wie die Ablaufzeit und eine eindeutige Benutzerkennung liefern. Wir empfehlen, ein Refresh-Token anzufordern und zu verwenden. Auf diese Weise muss sich ein Benutzer nur einmal bei BIMcollab Twin authentifizieren.

Verfügbare Scopes

  • bimlink_publicapi - Erforderlich für den Zugriff auf die öffentliche API von BIMcollab Twin
  • offline_access - Erforderlich für die Verwendung von Refresh-Tokens
  • openid - Fügt ein ID-Token zur Token-Antwort hinzu
  • email - Fügt die E-Mail-Adresse des Nutzers zum ID-Token hinzu (nur gültig, wenn auch openid angefordert wird)

Autorisierungsendpunkt - https://api.demo-bimlink.nl/connect/authorize

  • Die Umleitungs-URL sollte von unserem Authentifizierungsserver in die Whitelist aufgenommen werden.
  • Es kann ein Statuswert angegeben werden, um Cross-Site Request Forgery zu verhindern

Endpunkt für Zugangstoken - https://api.demo-bimlink.nl/connect/token

  • Die Verfallszeit ist im Zugriffstoken verfügbar.
  • Enthält ein Refresh-Token, wenn der Benutzer den Bereich offline_access gewährt hat

Token-Endpunkt aktualisieren - https://api.demo-bimlink.nl/connect/token

  • Liefert ein neues Zugriffstoken
  • Gleitender Ablauf, so dass die Lebensdauer des Refresh-Tokens jedes Mal zurückgesetzt wird, wenn ein neues Zugriffstoken angefordert wird
  • Sollte in einer POST-Anforderung mit den Daten im Body angefordert werden (Content-Type: application/x-www-form-urlencoded)
Die Daten, die von den Aktionen beantwortet werden, sind immer spezifisch für den aktuellen Benutzer (den Benutzer, für den das Zugriffstoken erstellt wurde). Verwenden Sie niemals Zugriffstoken für einen globalen Zweck, da die API nur Daten zurückgibt, die der Benutzer einsehen darf, und möglicherweise nicht den gesamten Datensatz. Der Umfang und die Berechtigungen eines jeden Benutzers werden im BIMcollab Twin vom Kontoadministrator verwaltet. Zum Beispiel: GET Locations für ein Domänenkonto gibt nur die Orte zurück, die der Benutzer sehen kann. Wird dieselbe Anfrage mit einem anderen Zugriffstoken durchgeführt, das einem anderen Benutzer gehört, kann die Antwort völlig andere Daten enthalten.

Schritt 2: Auswählen eines Domänenkontos

Alle Anfragen außer einer (Auflistung der verfügbaren Domänenkonten für einen Benutzer) erfordern eine DomainAccountId. Ein Domain-Account ist ein Unternehmenskonto und enthält alle Daten für ein bestimmtes Unternehmen oder ein sehr großes Projekt. Bevor Sie eine API-Abfrage senden können, müssen Sie zunächst ein Menü bereitstellen, das dem Benutzer die Auswahl eines Domain-Accounts ermöglicht. Wir empfehlen, das gewählte Domänenkonto zu speichern, da viele Benutzer nur ein einziges Domänenkonto für eine lange Zeit verwenden. In der eigentlichen Anfrage kann das Domainkonto wie folgt ausgewählt werden: https://api.demo-bimlink.nl/domainaccounts/{domainAccountId}/. Die folgende Aktion gibt die verfügbaren Domänenkonten für den Benutzer zurück: https: //api.demo-bimlink.nl/swagger/index.html#/DomainAccounts/DomainAccounts_GetAll

Schritt 3: Auswählen einer Projektphase

Viele API-Anfragen erfordern auch eine ProjectPhaseId, da die Daten innerhalb eines Kontos in einer Struktur von Standorten, Projekten und Projektphasen organisiert sind. Für die meisten Anwendungen wird der nächste Schritt nach dem Authentifizieren und der Auswahl eines Domänenkontos darin bestehen, ein Projektauswahlmenü anzuzeigen, damit der Benutzer ein Domänenkonto und eine Projektphase auswählen kann. Die folgende Aktion gibt die BIMcollab Twin Projektstruktur für ein Domänenkonto zurück: https: //api.test-bimlink.nl/swagger/index.html#/Locations/Locations_GetAll

Schritt 4: Auswählen eines Stockwerks

BIMcollab Twin bietet auch eine räumliche Struktur, um die Daten innerhalb einer Projektphase zu organisieren. Insbesondere bei der Abfrage von BIM-Daten ist es ratsam, dem Benutzer die Möglichkeit zu geben, ein bestimmtes Stockwerk auszuwählen, indem ein räumliches Auswahlmenü erstellt wird. Hinweis: Die räumlichen Strukturelemente (SpatialStructureElement) enthalten keine eigentlichen BIM-Daten, weitere Informationen finden Sie unter "BIM-Daten". Die folgende Aktion liefert die BIMcollab Twin Raumstruktur für eine Projektphase: https: //api.demo-bimlink.nl/swagger/index.html#/SpatialStructureElements/SpatialStructureElements_GetAll

Paginierung

API GET-Aktionen, bei denen erwartet wird, dass die Antwort eine große Anzahl von Objekten enthält, werden paginiert. Die Paginierung wird durch die Übermittlung eines Limits (maximale Anzahl der Objekte) und eines Offsets (Anzahl der zu überspringenden Objekte) im Querystring Ihrer Anfrage gesteuert. Der maximale Wert des Limits hängt von der Aktion ab und kann in der Swagger-Dokumentation nachgelesen werden. Pagination-Metadaten finden sich auch in den Headern der Antwort: Pagination-Limit, Pagination-Offset, Pagination-Result.

BIM-Daten

Die BIM-Daten in BIMcollab Twin werden meist aus IFC oder Revit importiert. Die Daten werden durch die folgenden Entitäten dargestellt:

Element

ElementType

Parameter



    • Related Articles

    • Power BI-Konnektor BIMcollab Twin

      Mit unserem eigenen Power BI-Konnektor können alle Daten aus der Gebäudedatei von BIMcollab Twin einfach in Power BI eingelesen werden. Es sind keine technischen Kenntnisse erforderlich, um Power BI und BIMcollab Twin zu verbinden. Mit diesem ...
    • BIMcollab Twin Spaces

      Jedes Konto auf BIMcollab Twin enthält Informationen aus Bauprojekten, die in einer eigenen Datenbank gespeichert werden und für die Projektteilnehmer zugänglich sind. Die Konten sind über eine eigene Webadresse mit einer eigenen Subdomain ...
    • Workflows in BIMcollab Twin

      Workflows dienen dazu, die verschiedenen Prozesse innerhalb eines Projekts in einen automatischen Arbeitsablauf zu übersetzen. Ein festgelegter Workflow startet, wenn ein neuer Beleg gebucht wird, der die vordefinierten Anforderungen erfüllt. Alle ...
    • Erste Schritte mit BIMcollab Twin für Administratoren

      Dieser Leitfaden beschreibt die Funktionalitäten und das Konfigurieren Ihres BIMcollab WebRaums. So können Sie im Handumdrehen loslegen. Ihr WebRaum wurde bereits von unserem Team aktiviert. Bei der Bestellung eines WebRaums wurden Sie gebeten, erste ...
    • Nutzeraktivitäten

      Ein BIMcollab Twin Raumadministrator kann ein detailliertes Liste aller Aktivitäten herunterladen, die ein Benutzer in einem BIMcollab Twin Raum durchgeführt hat, seit sie/er hinzugefügt wurde. Diese Logdatei kann aus dem Abschnitt "Benutzer" auf der ...