Erste Schritte im Bluebeam Developer Portal

Die Bluebeam API ist RESTful und verfügt zurzeit über 2 Kategorien an Endpunkten:

• Authentifizierung

• Studio

Es gibt regionsspezifische Basis-URLs, die für alle Endpunkte gelten:

- US: https://api.bluebeam.com

- DE: https://api.bluebeamstudio.de

- AU: https://api.bluebeamstudio.com.au

- UK: https://api.bluebeamstudio.co.uk

- SE: https://api.bluebeamstudio.se

https://api.bluebeam.com/publicapi/v1/sessions in den USA wäre also https://api.bluebeamstudio.com.au/publicapi/v1/sessions in AU.

Authentifizierung

Einige allgemeine Hinweise zur Handhabung der Authentifizierung:

• Authentifizierung mit OAuth 2.0

  • Alle API-Aufrufe werden im Kontext eines Benutzers durchgeführt. Durch die Authentifizierung mit OAuth gewähren Benutzer:innen Ihrer App die Berechtigung, auf ihre Daten zuzugreifen und in ihrem Namen API-Anfragen zu stellen.

• Alle Anfrage- und Antworttexte müssen JSON-formatiert sein. Legen Sie die Kopfzeile „Content-Type: applications/json“ für alle Anforderungen mit Textkörpern fest.

• API-Aufrufe müssen über HTTPS erfolgen.

• Weitere Informationen zur Einrichtung von OAuth 2.0 in Ihrer App finden Sie in unserem Authentifizierungsleitfaden.

Studio

Studio ist unsere cloudbasierte Plattform für die Zusammenarbeit mit einer direkten Verbindung zu unserer beliebtesten Desktop-Anwendung Bluebeam Revu. Unsere Studio-Endpunkte öffnen neue Kommunikationslinien für eine nahtlose Integration zwischen Studio und Ihren Systemen.

Im Allgemeinen handelt es sich bei den von der Studio-API bereitgestellten Funktionen um dieselben Funktionen, die ein Benutzer auch über die Studio-GUI in Revu erhalten würde.

Weitere Informationen zu Studio finden Sie auf unserer Studio-FAQ-Seite.

Um den Vorgang zu beschleunigen, empfehlen wir Ihnen die Verwendung einer App namens Postman. Dazu gehen Sie wie folgt vor:

1. Erstellen Sie zunächst ein Bluebeam Konto und fordern Sie Zugriff auf das Bluebeam Developer Portal an, falls das noch nicht passiert ist.

2. Gehen Sie zu Developers.bluebeam.com und melden Sie sich an.

3. Registrieren Sie sich, um Zugriff zu erhalten.

   1. Gehen Sie zu „Meine Apps“ und klicken Sie auf „Zugriff anfordern“.

   2. Füllen Sie das Formular zur Zugriffsanfrage aus (siehe Abbildung unten). Wählen Sie die Bluebeam API-Instanz aus, die Ihrer spezifischen Region zugeordnet ist.
      
      

   Hinweis zum Zuschusstyp:
   Aktivieren Sie nur die Kontrollkästchen neben:
   • Autorisierungscode
   • Aktualisieren Sie das Token

   3. Umleitungs-URI: Verwenden Sie https://oauth.pstmn.io/v1/callback

   4. Wählen Sie „Anfrage“ aus, um das Formular abzusenden.
      

   Genehmigungs-E-Mail
   Wenn Sie „Anfrage“ auswählen, erhalten Sie eine E-Mail von Multisoft mit dem Betreff „Anwendungsregistrierung genehmigt“ – bitte ignorieren. Dies ist ein weiterer unerwünschter Nebeneffekt unserer sofort einsatzbereiten Lösung.
   

4. Holen Sie sich Anmeldedaten. Ihre neu registrierte App sollte jetzt in der Liste angezeigt werden (aktualisieren Sie Ihren Browser, wenn Sie sie nicht sehen). Bewegen Sie den Mauszeiger über den Schlüssel, um Ihre Anmeldedaten zu erhalten.

   
   

5. Holen Sie sich einen Zugriffstoken über Postman.

   1. Greifen Sie über die Desktop-App oder den Browser auf Postman zu und erstellen Sie ein kostenloses Konto.

   2. Hier ist ein Skript, das Sie in Postman importieren können. Gehen Sie in Postman zu „Datei“ > „Importieren“ und fügen Sie das Skript ein.

   3. Um einen access_token in Postman zu erhalten, wählen Sie die Sammlung Bluebeam API (Script xxx) aus.

   4. Wechseln Sie zur Registerkarte „Autorisierung“ und ersetzen Sie die orangefarbenen Variablen {{client_id}} und {{client_secret}} durch die Client-ID und den Schlüssel, den Sie unter „Meine Apps“ erhalten haben.

   5. Scrollen Sie nach unten, und klicken Sie auf Neues Zugriffstoken abrufen.
      
      

   6. Melden Sie sich mit Ihrer BBID an und klicken Sie auf „Zugriff zulassen“,wenn Sie dazu aufgefordert werden. Sie erhalten ein Token, das Sie in Postman, unseren API-Dokumenten oder Ihrem eigenen Code verwenden können.

Hier finden Sie Schritt-für-Schritt-Anleitungen zur Migration einer vorhandenen Integration auf unsere neue Plattform.

1. Erstellen Sie ein BBID-Konto, falls Sie noch keins angelegt haben.

2. Gehen Sie zu Developers.bluebeam.com und melden Sie sich an.

3. Registrieren Sie eine neue App.

   1. Gehen Sie zu Meine Apps und wählen Sie „Zugriff anfordern“ aus.

   2. Füllen Sie das Formular zur Zugriffsanfrage aus (siehe Abbildung unten). Wählen Sie die Bluebeam API-Instanz aus, die Ihrer spezifischen Region zugeordnet ist.
      

      Hinweis zum Zuschusstyp:

      Aktivieren Sie nur die Kontrollkästchen neben:

      • Autorisierungscode
      • Aktualisieren Sie das Token

   3. Wählen Sie „Anfrage“ aus, um das Formular abzusenden.
      

4. Holen Sie sich Anmeldedaten. Ihre neu registrierte App sollte jetzt in der Liste angezeigt werden. Bewegen Sie den Mauszeiger über den Schlüssel, um Ihre Anmeldedaten zu erhalten.

   
   

5. Aktualisieren Sie Ihre bestehende Integration mit den unten aufgeführten neuen API-Routen für die Autorisierung und Studio-Endpunkte.
   

   Server der Vereinigten Staaten
   Umgebung	Ursprüngliche Basisroute	Neue Basislinie
   Auth – Produktion (US)	https://authserver.bluebeam.com/auth/oauth/authorize	https://api.bluebeam.com/oauth2/authorize
   Auth – Produktion (US)	https://authserver.bluebeam.com/auth/token	https://api.bluebeam.com/oauth2/token
   Studio – Produktion (US)	https://studioapi.bluebeam.com:443/publicapi/v1	https://api.bluebeam.com/publicapi/v1

6. Wenn Sie Ihre ältere Client-ID und Ihren älteren Clientschlüssel in Ihrer Integration konfiguriert haben, können Sie diese durch Ihre neue Client-ID und Ihren neuen Clientschlüssel ersetzen.

7. Fügen Sie in Ihren API-Aufrufen eine Kopfzeile namens „client_id„ mit dem Wert Ihrer neuen Client-ID hinzu. Dies ist für alle Anfragen erforderlich, die auf der neuen Plattform eingehen.

   Notiz
   Wir arbeiten noch daran, unsere Fehlermeldungen genauer und aussagekräftiger zu gestalten, aber wenn Sie Ihre Anfrage ohne die Kopfzeile „client_id“ senden, werden Ihnen in der Zwischenzeit folgende Fehlermeldung angezeigt:
   

   copy

   {
       "msg": "Internal Server Error"
   }

8. Unsere neue Plattform handhabt die Authentifizierung ein wenig anders als unsere alte, daher empfehlen wir Ihnen, unseren neuen Authentifizierungsleitfaden zu lesen. Zwei nennenswerte Änderungen:

   • Wir haben einen offline_access-Bereich für Aktualisierungstoken eingeführt (siehe Schritt 1 im Authentifizierungsleitfaden).

   • Die Antworten unserer Token-Endpunkte haben sich geändert (Beispielantworten finden Sie im Authentifizierungsleitfaden).

9. Wenn alles korrekt konfiguriert ist, sollten Sie für alle Studio-Endpunkte eine Antwort erhalten, die mit der Antwort der vorherigen Studio-API identisch ist.
   Wenn Sie beispielsweise eine Liste mit Studio-Projekten angefordert haben, würde Ihr Antworttext ungefähr wie folgt aussehen:
   

   copy

   {
     "$id": "1"
     "Projects": [
       {
         "$id": "2",
         "Id": "385-509-537",
         "Guid": "Mzu1D6xhLE2bE0y2F4ozfQ",
         "Name": "Name des Testprojekts",
         "Restricted": true,
         "Created": "2024-02-29T17:40:58.043",
         "OwnerNameIdentifier": "e149e277-3052-4f3e-a376-29fc6c5aa76c",
         "OwnerEmail": "jdoe@bluebeam.com"
       }
     ]
   }

10. Geschafft! Testen Sie Ihre App und teilen Sie uns mit, wenn Sie Probleme haben.