Guide de la session de Studio

Le portail des développeurs Bluebeam est uniquement disponible pour les clients actifs dans la région des États-Unis.

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 nombreuses fonctionnalités dans la section Studio de notre documentation API. Consultez notre guide de démarrage dans le portail des développeurs Bluebeam pour obtenir des instructions sur la façon d'obtenir un jeton d'accès valide.

Cycle de vie des sessions en studio

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

  1. Initialisation – Ouvre la « salle de conférence numérique »

  2. Ajoutez des fichiers PDF à la session pour les visualiser et les annoter

  3. Ajoutez des utilisateurs à la session afin qu'ils puissent visualiser et annoter

  4. Finalisation – Ferme la session et renvoie les PDF balisés à leur système d'origine

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

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

Doit être formaté au format UTC.

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

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

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

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

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

  1. Créez le bloc de métadonnées pour le fichier via l'API Bluebeam

  2. Téléchargez le fichier directement sur AWS

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

Point final

copy 
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

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

Exemple de réponse

copy 
{
  "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.

Une fois que vous disposez d'un espace réservé au bloc de métadonnées pour votre fichier, effectuez une requête PUT sur l' UploadURL renvoyée par la requête POST précédente. Dans votre requête PUT , incluez les éléments suivants dans l'en-tête :

  • “x-amz-server-side-encryption” avec la valeur “AES256”

  • “Content-Type” avec la valeur “application/pdf”

Point final

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

Exemple de cURL

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

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 .

 

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 :

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

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

Paramètres

Nom

Description

Email

Adresse e-mail à laquelle envoyer l'invitation

Message

Message personnalisé qui s'affiche dans l'e-mail

Exemple

copy 
cURL [https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/invite](https://api.bluebeam.com/publicapi/v1/sessions/123-456-789/invite) \
-H "Authorization: Bearer {valid access_token}" \
-H "Content-Type: Application/JSON" \
-H "client_id: [your client id]" \
-d '{  
      "[Email":"gavin.belson@hooli.com](mailto:Email%22:%22gavin.belson@hooli.com)",  
      "Message":"Please join this Session to review documents regarding the Pied Piper acquisition."
    }' \
-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 .

OU

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

copy 
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é

Message

Message personnalisé qui s'affiche dans l'e-mail

Exemple

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](mailto:peter.gregory@raviga.com)",  
      "SendEmail": true,  
      "Message": "As requested, here is the Session to review the Pied Piper acquisition documents."
    }' \
-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

 

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.

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

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

Exemple

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

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 balisage dans un seul PDF afin que les balisages soient visibles sur le PDF en dehors de la session Studio.

Point final

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

Exemple

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

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

Exemple

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

Corps de la réponse

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

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.

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

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

Exemple de clôture d'une session

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

 

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 :