Erste Schritte im Bluebeam Developer Portal

Das Bluebeam Developer Portal zur Entwicklung von Integrationen ist nur für aktive Kunden, Vertriebspartner und Softwarepartner in den Regionen US, AU, DE, UK und SE verfügbar.

Diese Seite ist Ihr Leitfaden für unser neues Entwicklerportal. Wir empfehlen Ihnen, das Dokument in einer eigenen Registerkarte zu öffnen, während Sie die Schritte in einer separaten Registerkarte ausführen.

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

Wählen Sie Ihren Pfad:

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.

Wir nehmen Postman als Beispiel, das Vorgehen funktioniert aber auch mit anderen API-Softwareprogrammen.

So erhalten Sie einen Zugriffstoken:

Für das Verfahren benötigen Sie Daten aus dem Authentifizierungshandbuch.

  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. Fordern Sie den Zugriff an und erstellen Sie eine Client-ID.

    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 Region zugeordnet ist.

      Die Bluebeam Developer API ist der Server in den USA.

      3. Die Bluebeam-API unterstützt nur die folgenden Auswahlen für Grant Type:
      • Autorisierungscode
      • Aktualisierungstoken

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

      Diese URI ist speziell für Aufrufe in Postman bestimmt. Andere API-Werkzeuge oder Ihre eigene App benötigen eine andere URI.

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

      5. 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. Das Skript können Sie in Postman importieren . Das Skript ist eine Sammlung aller verfügbaren Bluebeam-API-Aufrufe. 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. Wählen Sie die Registerkarte Autorisierung , um in Postman ein neues Token zu konfigurieren.

      Weitere Informationen zur Authentifizierung finden Sie im Authentifizierungsleitfaden. Im Authentifizierungsleitfaden stehen Anfrageparameter; diese werden in Postman als „Variablen“ bezeichnet.
      Sie können entweder eine Umgebung in Postman einrichten, um Variablen für Ihre Autorisierung zu erstellen, oder Sie füllen die erforderlichen WerteClosed manuell aus.

      Erforderliche Einstellungen und Werte in Postman:

      • Authentifizierungstyp: Muss OAuth 2.0 sein

      • Berechtigungstyp: Autorisierungscode

      • Token-Name: Code

      • Berechtigungstyp: Autorisierungscode

      • Die Autorisierung über den Browser muss aktiviert sein.

      • Authentifizierungs-URL: https://api.bluebeam.com/oauth2/authorize

      • Zugriffstoken-URL: https://api.bluebeam.com/oauth2/token

      • Client-ID: Die während des App-Registrierungsprozesses erhaltene Client-ID

      • Client-Geheimnis: Das Client-Geheimnis, das Sie während des App-Registrierungsprozesses erhalten haben.

      • Umfang: Umfang für Studio-Endpunkte; die Mindestanforderung ist „offline_access“

      • Status: Status

      • Clientauthentifizierung: Client-Anmeldeinformationen im Nachrichtentext senden

    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.

Ablaufdatum des Tokens
Token laufen nach einer Stunde ab, wenn Ihre Anrufe also nicht mehr funktionieren, führen Sie den Prozess also erneut durch, um einen neuen Token zu erhalten. Informationen zur Einrichtung von OAuth zur Verwendung von Aktualisierungstoken finden Sie in unserem Authentifizierungsleitfaden .

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. Testen Sie Ihre App und teilen Sie uns mit, falls Probleme auftreten.

 

Zusätzliche Ressourcen:


Ressourcen

Revu 21

Developer Portal

Developer Portal

Diese Seite ist unser Leitpfaden durch unser neues Developer Portal.