Studio-Sitzung – Leitfaden

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.

Sie können sich Studio-Sitzungen wie einen digitalen Konferenzraum vorstellen, in dem PDF-Pläne entweder gleichzeitig oder asynchron mit Markierungen versehen werden können. Diese Anleitung behandelt den allgemeinen Lebenszyklus einer Studio-Sitzung und enthält Codebeispiele. Um mehr über Studio und Studio-Sitzungen im Allgemeinen zu erfahren, besuchen Sie unsere Studio-FAQ-Seite.

Sie können diesem Leitfaden folgen und viele der Sprechblasen im Abschnitt „Studio“ unserer API-Dokumente ausprobieren. Anweisungen zum Erhalten eines gültigen Zugriffstokens finden Sie in unserer Anleitung zu „Erste Schritte“ im Bluebeam Entwicklerportal.

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.

Lebenszyklus von Studio-Sitzungen

Der Lebenszyklus einer Studio-Sitzung besteht aus vier Teilen:

Initialisierung – Öffnet den „digitalen Konferenzraum“
Fügen Sie PDFs zur Sitzung hinzu, um sie anzuzeigen und mit Markierungen zu versehen
Fügen Sie Benutzer zur Sitzung hinzu, damit sie Kommentare anzeigen und Markierungen hinzufügen können
Abschließen – Schließt die Sitzung ab und gibt die mit Markierungen versehenen PDFs in ihr ursprüngliches System zurück

1. Initialisieren Sie die Sitzung

Die erste Phase im Lebenszyklus einer Studio-Sitzung ist die Erstellung. Geben Sie zunächst einen POST-Befehl mit den folgenden Parametern an den Sitzungsendpunkt ein.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions

Achten Sie darauf, client_id in der Kopfzeile Ihrer Anfrage zu enthalten.

Parameter anfordern

Name	Beschreibung	Werttyp / Mögliche Werte
`Name`	Sitzungsbezeichnung	String
`Notification`	`true`: Der aktuelle Benutzer erhält E-Mail-Benachrichtigungen über Änderungen an dieser Sitzung. `false`: Der aktuelle Benutzer erhält keine E-Mail-Benachrichtigungen über Änderungen an dieser Sitzung.	Boolean
`Restricted`	`true`: Die Sitzung wird auf E-Mail-Adressen beschränkt, die eingeladen oder hinzugefügt wurden. `false`: Die Sitzung kann von allen Benutzern geöffnet werden, die über die 9-stellige Sitzungs-ID verfügen.	Boolean
`SessionEndDate`	Sobald dieses Datum erreicht ist, werden alle Teilnehmer:innen mit Ausnahme des Moderators aus der Sitzung entfernt.	Must be formatted in UTC format.
`DefaultPermissions`	Dieses Berechtigungsset gilt für alle Benutzer, die zu dieser Sitzung hinzugefügt werden, mit Ausnahme des Moderators (den aktuellen Benutzer). Der Moderator erhält die volle Kontrolle.	Definieren Sie die Berechtigungsarten und -berechtigungen weiter unten.

Zugriff	Beschreibung	Werttyp / Mögliche Werte
`Type`	Berechtigungstyp	Kopie`speichern – Teilnehmern erlauben, unter zu speichern.` `Printkopie` – Teilnehmern erlauben, die in der Sitzung enthaltenen PDFs auszudrucken. `Markierung –` Teilnehmern das Hinzufügen von Markierungen erlauben. `Dokumente` hinzufügen – Teilnehmer können neue Dokumente zur Sitzung hinzufügen. `Vollständige` Kontrolle – Gewähren Sie Teilnehmer:innen Administratorrechte für die Sitzung. `MarkupAlert –` Teilnehmern erlauben, während der Sitzung Markierungswarnungen zu senden und zu empfangen.
`Allow`	Berechtigungsstatus:	„Zulassen“, „Verweigern“, „Standard“.

Zugriff

Beschreibung

Werttyp / Mögliche Werte

Type

Berechtigungstyp

Kopiespeichern – Teilnehmern erlauben, unter zu speichern.

Printkopie – Teilnehmern erlauben, die in der Sitzung enthaltenen PDFs auszudrucken.

Markierung – Teilnehmern das Hinzufügen von Markierungen erlauben.

Dokumente hinzufügen – Teilnehmer können neue Dokumente zur Sitzung hinzufügen.

Vollständige Kontrolle – Gewähren Sie Teilnehmer:innen Administratorrechte für die Sitzung.

MarkupAlert – Teilnehmern erlauben, während der Sitzung Markierungswarnungen zu senden und zu empfangen.

Allow

Berechtigungsstatus:

„Zulassen“, „Verweigern“, „Standard“.

Enddatum der Sitzung
Enddaten für Sitzungen sind nicht erforderlich, aber wenn ein Sitzungsenddatum ausgewählt wird, werden Teilnehmer:innen der Sitzung 7 Tage, 2 Tage und 24 Stunden vor dem Ablaufdatum per E-Mail benachrichtigt.

cURL-Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions](https://api.bluebeam.com/publicapi/v1/sessions) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{

    "Name":"Pied Piper Acquisition Review",

    "Notification": true,

    "Restricted": true,

    "SessionEndDate": "2016-08-17T21:09:07.5174221Z",

    "DefaultPermissions":[  
      {  
        "Type":"SaveCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"PrintCopy",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"Markup",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"MarkupAlert",  
        "Allow":"Allow"  
      },  
      {  
        "Type":"AddDocuments",  
        "Allow":"Deny"  
      }  
    ]
}' \
-X POST

Berechtigungen
Derzeitige Benutzer:innen von Studio sind oft an bestimmte Standardberechtigungen gewöhnt. Es empfiehlt sich immer, entweder die Standardberechtigungen zu überprüfen oder Benutzer:innen die Möglichkeit zu geben, ihre Berechtigungen auszuwählen. Wenn Sie die Bluebeam API zum Festlegen von Berechtigungen verwenden, ist der Standardwert „Verweigern“ eingestellt.

Antworttext

copy

{
    "$id": "1",
    "Id": "123-456-789"
}

2. PDF-Dateien hinzufügen

Im nächsten Schritt werden die PDF-Dateien hinzugefügt. Zum Hinzufügen von Dateien stehen drei Schritte zur Verfügung:

Erstellen Sie den Metadatenblock für die Datei über die Bluebeam API
Laden Sie die Datei direkt in AWS hoch
Bestätigen Sie den Upload über die Bluebeam API

Hinweis: PDF/A-Dateien werden in Studio-Sitzungen nicht unterstützt.
Da PDF/A ein Archivformat ist, ist keine Bearbeitung möglich, weshalb Schritt 4 unten fehlschlägt.

a. Metadatenblock erstellen

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files

Parameter

Name	Beschreibung	Werttyp / Mögliche Werte
`Name`	Name der Datei	String endet auf „.pdf“
`Source`	Quellpfad; So können Sie später im Verfahren feststellen, woher die Datei stammt	String
`Size`	Dateigröße; Lassen Sie leer, damit der Server die Berechnung durchführen kann	Ganzzahl
`CRC`	Lassen Sie null, damit der Server berechnet werden kann	String

cURL-Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client_id]" \
-d '{  
      "Name":"Pied_Piper_Acquisition.pdf",  
      "Source":"[https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf](https://portfolio.raviga.com/primarybets/piedpiper/legaldocs/Pied_Piper_Acquisition.pdf)"
    }' \
-X POST

Beispielantwort

copy

{
  "Id": 1234567
  "UploadUrl":"{upload file to this URL}"
  "UploadContentType":"Application/PDF"
}

Upload-Fenster
Die Upload-URL ist 10 Minuten lang gültig, um das Hochladen zu starten.

c. Bestätigen Sie das Hochladen

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/confirm-upload

cURL-Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/confirm-upload) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X POST

Antwort

Im Erfolgsfall erhalten Sie die Antwort „204“. Informationen zu Fehlern finden Sie unten in unserem Authentifizierungsleitfaden unter „Häufige HTML-Antwortcodes“.

3. Fügen Sie Benutzer hinzu

Da Sie nun eine Sitzung mit PDFs haben, ist es an der Zeit, Benutzer zu der Sitzung hinzuzufügen. Der Initiator der Sitzung (der aktuelle Benutzer) wird automatisch zum Moderator der Sitzung ernannt und wird automatisch zu den Benutzern der Sitzung hinzugefügt. Weitere Benutzer können jederzeit hinzugefügt werden, während die Sitzung aktiv ist. Zum Hinzufügen von Benutzern stehen zwei Methoden zur Auswahl:

Methode A: Benutzer einladen

Diese Methode eignet sich am besten, um Benutzer:innen einzuladen, die noch kein Studio-Konto haben. Der oder die Teilnehmer:in erhält eine E-Mail mit der Möglichkeit, ein kostenloses Studio-Konto zu erstellen.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/invite

Parameter

Name	Beschreibung
`Email`	E-Mail-Adresse, an die Einladung gesendet werden soll
`Nachricht`	Benutzerdefinierte Nachricht, die in der E-Mail angezeigt wird

Beispiel

copy

cURL https://api.bluebeam.com/publicapi/v1/sessions/{session}/invite \
-H "Authorization: Bearer {token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: {client_id}" \
-d '{  
      "Email":"gavin.belson@hooli.com",  
      "Message":"Bitte nehmen Sie an dieser Sitzung teil, um die Dokumente zur Übernahme von Pied Piper zu prüfen."
    }' \
-X POST

Antwort

Im Erfolgsfall erhalten Sie die Antwort „204“. Informationen zu Fehlern finden Sie unten in unserem Authentifizierungsleitfaden unter „Häufige HTML-Antwortcodes“.

ODER

Methode B: Benutzer hinzufügen

Diese Methode eignet sich am besten, wenn Sie wissen, dass die E-Mail-Adresse bereits mit einem Studio-Konto verknüpft ist und Sie möchten, dass diese E-Mail-Adresse zu einer Studio-Sitzung hinzugefügt wird, ohne sich anzumelden. Wenn der oder die Benutzer:in kein Konto hat oder sich nicht sicher ist, ob er eins hat, verwendet er Methode A: „Benutzer einladen“. Mit Methode B: „Benutzer hinzufügen“ wird der Benutzer zu den Teilnehmern der Studio-Sitzung hinzugefügt und die Studio-Sitzung wird in der Registerkarte „Studio“ der Revu-Benutzeroberfläche unter den betreffenden Sitzungen angezeigt.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/users

Parameter

Name	Beschreibung
`Email`	E-Mail-Adresse des bekannten Studio-Kontos
`SendEmail`	Boolean; Richtig: Senden Sie eine E-Mail an den Eingeladenen
`Nachricht`	Benutzerdefinierte Nachricht, die in der E-Mail angezeigt wird

Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/users)
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "Email": "peter.gregory@raviga.com",
      "SendEmail": true,
      "Message": "Wie gewünscht, finden Sie hier die Sitzung zur Überprüfung der Dokumente zur Übernahme von Pied Piper."
    }' \
-X POST

Antwort

Im Erfolgsfall erhalten Sie die Antwort „204“. Informationen zu Fehlern finden Sie unten in unserem Authentifizierungsleitfaden unter „Häufige HTML-Antwortcodes“.

Beispiel-E-Mail für eine Sitzungseinladung

4. Schließen Sie die Sitzung ab

Um eine Sitzung zu beenden (in der Regel nachdem die Teilnehmer:innen die Markierung abgeschlossen haben oder das Ablaufdatum der Sitzung erreicht wurde), muss der Status geändert, die Dateien bearbeitet und die Sitzung selbst ordnungsgemäß entsorgt werden.

a. Setzen Sie den Status auf „Wird abgeschlossen“.

Wenn Sie den Status einer Sitzung auf „Wird abgeschlossen“ setzen, werden alle Benutzer:innen aus der Sitzung entfernt. Dies dient dazu, weitere Änderungen an den Sitzungsdateien nach dem Herunterladen zu verhindern.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{id}

Beispiel

copy

cURL https://api.bluebeam.com/publicapi/v1/sessions/123-456-789 \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{"Status": "Finalizing"}' \
-X PUT

b. Laden Sie die mit Markierungen versehenen Sitzungsdateien herunter

Das Herunterladen der Sitzungsdateien mit Markierungen ist ein zweiteiliger Vorgang. Führen Sie die folgenden Schritte für jede Datei in der Sitzung aus.

i. Erstellen Sie eine Momentaufnahme

In einer Sitzung werden PDFs und Markierungen separat gespeichert. Eine Momentaufnahme kombiniert den PDF-Inhalt mit der Markierungsebene in einer einzigen PDF-Datei, sodass die Markierungen auch außerhalb der Studio-Sitzung in der PDF-Datei sichtbar sind.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/snapshot) \
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \

ii. Prüfen Sie den Status der Momentaufnahme und laden Sie sie herunter, wenn Sie fertig sind

Senden Sie eine get-Anfrage an den Endpunkt der Momentaufnahme, bis der Status entweder „Complete“ oder „Error“ lautet.

Bei Fehler: Wir fügen eine Fehlermeldung ein, die dem Benutzer angezeigt werden kann.
Falls abgeschlossen:Laden Sie die Momentaufnahme mithilfe der Download-Url herunter

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{sessionId}/files/{id}/snapshot

Beispiel

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/files/1234567/)
-H "Authorization: Bearer {valid access_token}" \
-H "client_id: [your client id]" \
-X GET

Antworttext

copy

{
    "Status": "Complete",
    "StatusTime": "{The last time the Status was changed}",
    "LastSnapshotTime": "{Time of last successful Snapshot}",
    "DownloadUrl": "{A download URL for the last successful Snapshot}"
}

Statusoptionen

Status	Beschreibung
`NoSnapshot`	Wenn noch nie eine Momentaufnahme für eine Datei aufgerufen wurde
`Requested`	Der Momentaufnahmeauftrag wurde noch nicht gestartet, wir haben jedoch die Anfrage erhalten
`InProgress`	Der Momentaufnahmeauftrag wird ausgeführt
`Complete`	Der Momentaufnahmeauftrag ist abgeschlossen und kann über `DownloadUrl heruntergeladen werden`
`Error`	Erstellung der Momentaufnahme fehlgeschlagen. Der Status enthält eine Fehlermeldung.

c. Schließen Sie die Sitzung

Da Sie nun die PDF-Datei(en) mit Markierungen haben, können Sie die Sitzung löschen, indem Sie eine DELETE-Anfrage an den Endpunkt mit der Sitzungs-ID senden.

Endpunkt

copy

https://api.bluebeam.com/publicapi/v1/sessions/{id}

Beispiel für den Abschluss einer Sitzung

copy

cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-X DELETE

Schlussfolgerung

Das Zurücksetzen der Datei an ihren ursprünglichen Speicherort und das Archivieren der Sitzung schließen den typischen Lebenszyklus einer Studio-Sitzung ab. Es gibt viele verschiedene Möglichkeiten, mit Studio-Sitzungen zu arbeiten, aber wir hoffen, dass Ihnen diese Anleitung die Grundlagen vermittelt hat.

Zusätzliche Ressourcen:

Ressourcen

Revu 21

Developer Portal

Dieser Leitpfaden zum Developer Portal behandelt den allgemeinen Lebenszyklus einer Studio-Sitzung und enthält Codebeispiele.