Guide de la session de Studio

Le Bluebeam Developer Portal, destiné au développement d’intégrations, est uniquement accessible pour les clients actifs, les partenaires de distribution et les partenaires logiciels dans les régions États-Unis, Australie, Allemagne, Royaume-Uni et Suède.

Considérez une session en studio comme une salle de conférence numérique où les dessins PDF peuvent être annotés simultanément ou de manière asynchrone. Ce guide couvre le cycle de vie général d'une session Studio et inclut des exemples de code. Pour en savoir plus sur le Studio et les sessions en studio en général, visitez notre page FAQ sur le Studio.

Vous pouvez suivre ce guide et essayer de nombreux appels dans la section Studio de notre documentation API. Consultez notre guide Démarrer dans le portail des développeurs Bluebeam pour obtenir des instructions sur la façon d'obtenir un jeton d'accès valide.

Il existe des URL de base spécifiques à la région qui s'appliquent à tous les points de terminaison :

États-Unis : https://api.bluebeam.com
DE : https://api.bluebeamstudio.de
AU : https://api.bluebeamstudio.com.au
Royaume-Uni : https://api.bluebeamstudio.co.uk
– SE : https://api.bluebeamstudio.s

Par exemple, https://api.bluebeam.com/publicapi/v1/sessions aux États-Unis serait https://api.bluebeamstudio.com.au/publicapi/v1/sessions en Australie.

Cycle de vie des sessions en studio

Le cycle de vie d'une session en studio peut être divisé en 4 parties :

Initialisation – Ouvre la « salle de conférence numérique »
Ajoutez des fichiers PDF à la session pour les visualiser et les annoter
Ajoutez des utilisateurs à la session afin qu'ils puissent visualiser et annoter
Finalisation – Ferme la session et renvoie les PDF balisés à leur système d'origine

1. Initialiser la session

La première phase du cycle de vie d'une session studio est sa création. Pour commencer, exécutez une commande POST sur le point de terminaison Sessions avec les paramètres suivants.

Point final

Copier

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

Assurez-vous d'inclure client_id dans l'en-tête de votre demande.

Paramètres de la requête

Nom	Description	Type de valeur / Valeurs possibles
`Nom`	Nom de la session	Chaîne
`Notification`	`true`: l'utilisateur actuel sera abonné aux notifications par e-mail concernant les modifications apportées à cette session. `false`: L'utilisateur actuel ne sera pas abonné aux notifications par e-mail concernant les modifications apportées à cette session.	Booléen
`Restricted`	`true`: restreint la session aux seules adresses e-mail qui ont été invitées ou ajoutées. `false`: laisse la session ouverte à toute personne disposant de l'ID de session à 9 chiffres.	Booléen
`SessionEndDate`	Une fois cette date atteinte, tous les participants, à l’exception de l’hôte, seront retirés de la session.	Must be formatted in UTC format.
`DefaultPermissions`	Cet ensemble d’autorisations s’appliquera à tous les utilisateurs ajoutés à cette session, à l’exception de l’hôte (l’utilisateur actuel). L'hôte obtient le contrôle total.	Définissez les types d’autorisations et les autorisations elles-mêmes ci-dessous.

Autorisation	Description	Type de valeur / Valeurs possibles
`Type`	Type d'autorisation	`SaveCopy` – Autoriser les participants à enregistrer sous. `PrintCopy` – Autoriser les participants à imprimer les PDF inclus dans la session. `Markup` – Autorisez les participants à placer des annotations. `AddDocuments` – Autoriser les participants à ajouter de nouveaux documents à la session. `FullControl` – Accordez aux participants des droits d’administrateur sur la session. `MarkupAlert` – Autorisez les participants à envoyer et à recevoir des alertes de marquage pendant la session.
`Allow`	État d'autorisation	Autoriser, Refuser, Par défaut

Autorisation

Description

Type de valeur / Valeurs possibles

Type

Type d'autorisation

SaveCopy – Autoriser les participants à enregistrer sous.

PrintCopy – Autoriser les participants à imprimer les PDF inclus dans la session.

Markup – Autorisez les participants à placer des annotations.

AddDocuments – Autoriser les participants à ajouter de nouveaux documents à la session.

FullControl – Accordez aux participants des droits d’administrateur sur la session.

MarkupAlert – Autorisez les participants à envoyer et à recevoir des alertes de marquage pendant la session.

Allow

État d'autorisation

Autoriser, Refuser, Par défaut

Date de fin de session
Les dates de fin de session ne sont pas obligatoires, mais si une date de fin de session est sélectionnée, les participants à la session seront informés par courrier électronique 7 jours, 2 jours et 24 heures avant la date d'expiration.

Exemple de cURL

Copier

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

Autorisations
Les utilisateurs actuels de Studio sont souvent habitués à des valeurs par défaut d'autorisations spécifiques. C'est toujours une bonne idée de vérifier quelles devraient être les autorisations par défaut ou de permettre aux utilisateurs de choisir leurs autorisations. Lorsque vous utilisez l'API Bluebeam pour définir des autorisations, « Refuser » est la valeur par défaut.

Corps de la réponse

Copier

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

2. Ajoutez des PDF

L'étape suivante consiste à ajouter les fichiers PDF. L'ajout de fichiers est un processus en 3 étapes :

Créez le bloc de métadonnées pour le fichier via l'API Bluebeam
Téléchargez le fichier directement sur AWS
Confirmer le téléchargement via l'API Bluebeam

Remarque : les sessions en studio ne prennent pas en charge les fichiers PDF/A.
Étant donné que PDF/A est un format d’archivage, il ne permet pas l’édition et entraînera l’échec de l’étape 4 ci-dessous.

a. Créer un bloc de métadonnées

Point final

Copier

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

Paramètres

Nom	Description	Type de valeur / Valeurs possibles
`Nom`	Nom du fichier	Chaîne se terminant par « .pdf »
`Source`	Chemin source ; cela peut vous aider à identifier la provenance du fichier plus tard dans le processus	Chaîne
`Size`	Taille du fichier ; laissez null pour que le serveur puisse calculer	Entier
`CRC`	Laissez null pour que le serveur calcule	Chaîne

Exemple de cURL

Copier

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

Exemple de réponse

Copier

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

Fenêtre de téléchargement
L'URL de téléchargement est valide pendant 10 minutes pour démarrer le téléchargement.

c. Confirmer le téléchargement

Point final

Copier

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

Exemple de cURL

Copier

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

Réponse

En cas de succès, vous recevrez une réponse 204 . Pour les erreurs, consultez les codes de réponse HTML courants au bas de notre Guide d'authentification .

3. Ajouter des utilisateurs

Maintenant que vous disposez d'une session contenant des fichiers PDF, il est temps d'ajouter des utilisateurs à la session. L'initiateur de la session (l'utilisateur actuel) devient automatiquement l'hôte de la session et est automatiquement ajouté aux utilisateurs de la session. D'autres utilisateurs peuvent toujours être ajoutés pendant que la session est active. Il existe 2 méthodes pour ajouter des utilisateurs :

Méthode A : Inviter l'utilisateur

Cette méthode est idéale pour inviter des utilisateurs qui n’ont peut-être pas encore de compte Studio. Un e-mail est envoyé à l'invité avec la possibilité de créer un compte Studio gratuit.

Point final

Copier

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

Paramètres

Nom	Description
`Email`	Adresse e-mail à laquelle envoyer l'invitation

Exemple

Copier

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":"Nous vous invitons à participer à cette session afin d’examiner les documents relatifs à l’acquisition de Pied Piper."
    }’ \
-X POST

Réponse

En cas de succès, vous recevrez une réponse 204 . Pour les erreurs, consultez les codes de réponse HTML courants au bas de notre Guide d'authentification .

Méthode B : Ajouter un utilisateur

Cette méthode est idéale si vous savez que l’adresse e-mail est déjà associée à un compte Studio et que vous souhaitez qu’elle soit ajoutée à une session Studio sans inscription. Si l'utilisateur n'a pas de compte ou s'il n'est pas sûr d'en avoir un, utilisez la méthode A : Inviter l'utilisateur. À l'aide de la méthode B : Ajouter un utilisateur, l'utilisateur est ajouté aux participants de la session Studio et la session Studio apparaît sous ses sessions suivies dans l'onglet Studio de l'interface Revu.

Point final

Copier

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

Paramètres

Nom	Description
`Email`	Adresse e-mail du compte Studio connu
`SendEmail`	Booléen ; Vrai : envoyer un e-mail à l'invité, Faux : ne pas envoyer de notification par e-mail à l'invité

Exemple

Copier

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": "Conformément à votre demande, voici la session permettant de consulter les documents relatifs à l’acquisition de Pied Piper."
    }’ \
-X POST

Réponse

En cas de succès, vous recevrez une réponse 204 . Pour les erreurs, consultez les codes de réponse HTML courants au bas de notre Guide d'authentification .

Exemple d'e-mail d'invitation à une session

4. Finaliser la session

Pour mettre fin à une session (généralement effectué une fois que les participants ont fini de marquer ou que la date d'expiration de la session a été atteinte), son statut doit être modifié, ses fichiers doivent être traités et la session elle-même doit être correctement éliminée.

a. Définir le statut sur Finalisation

Définir le statut d'une session sur Finalisation supprime tous les utilisateurs de la session, à l'exception de l'hôte. Ceci est fait pour empêcher d’autres modifications apportées aux fichiers de session après leur téléchargement.

Point final

Copier

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

Exemple

Copier

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. Téléchargez les fichiers de session balisés

Le téléchargement des fichiers de session balisés est un processus en 2 parties. Suivez les étapes ci-dessous pour chaque fichier de la session.

i. Créer un instantané

Pendant une session, les PDF et les annotations sont stockés séparément. Un instantané combine le contenu PDF avec la couche de marquage dans un seul PDF afin que les marquages soient visibles sur le PDF en dehors de la session Studio.

Point final

Copier

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

Exemple

Copier

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. Vérifiez l'état de l'instantané, téléchargez-le s'il est terminé

Effectuez une requête GET au point de terminaison Snapshot jusqu'à ce que le Status soit Complete ou Error.

Si Error: Nous inclurons un message d’erreur qui peut être présenté à l’utilisateur.
Si Complete: utilisez l' DownloadUrl pour télécharger l'instantané

Point final

Copier

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

Exemple

Copier

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

Corps de la réponse

Copier

{
    "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}"
}

Options de statut

Statut	Description
`NoSnapshot`	Lorsqu'un Snapshot n'a jamais été appelé sur un fichier
`Requested`	La tâche Snapshot n'a pas encore démarré, mais nous avons reçu la demande
`InProgress`	La tâche Snapshot est en cours
`Complete`	Le travail Snapshot est terminé et peut être téléchargé via `DownloadUrl`
`Error`	La tâche de capture instantanée a échoué. Le statut inclura un message d'erreur.

c. Clôturer la session

Maintenant que vous disposez des fichiers PDF balisés, vous pouvez supprimer la session en envoyant une demande DELETE au point de terminaison de l'ID de session.

Point final

Copier

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

Exemple de clôture d'une session

Copier

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

Conclusion

Le retour du fichier à son emplacement d’origine et l’archivage de la session complètent le cycle de vie typique d’une session Studio. Bien qu'il existe de nombreuses façons différentes de travailler avec Studio Sessions, nous espérons que cette présentation vous a donné une bonne compréhension des bases.

Voir aussi :

Ressources

Revu 21

Developer Portal

Ce guide du Developer Portal couvre le cycle de vie général d’une session Studio et inclut des exemples de code.