Navigieren durch BIMcollab Twin Public API

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.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.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.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.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.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.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.