Guida alle sessioni Studio

Il Bluebeam Developer Portal, dedicato allo sviluppo delle integrazioni, è disponibile solo per clienti attivi, partner di canale e partner software nelle Aree USA, AU, DE, UK e SE.

Immagina una sessione Studio come una sala conferenze digitale in cui i disegni PDF possono essere annotati simultaneamente o in modo asincrono. Questa guida illustra il ciclo di vita generale di una sessione Studio e include esempi di codice. Per saperne di più sullo Studio e sulle Sessioni Studio in generale, visita la nostra pagina delle FAQ sullo Studio.

Puoi seguire questa guida e provare molte delle chiamate nella sezione Studio della nostra documentazione API. Per istruzioni su come ottenere un token di accesso valido, consulta la nostra guida introduttiva al Bluebeam Developer Portal.

Esistono URL di base specifici per Area che si Applica a tutti gli endpoint:

Ad esempio, https://api.bluebeam.com/publicapi/v1/sessions negli Stati Uniti sarebbe https://api.bluebeamstudio.com.au/publicapi/v1/sessions in Australia.

Ciclo di vita delle Sessioni Studio

Il ciclo di vita di una sessione Studio può essere diviso in 4 parti:

Inizializzazione – Apre la "sala conferenze digitale"
Aggiungi PDF alla Sessione per la visualizzazione e per annotare
Aggiungi utenti alla Sessione in modo che possano visualizzare e annotare
Finalizzazione: chiude la sessione e restituisce i PDF contrassegnati al sistema di origine

1. Inizializza la sessione

La prima fase del ciclo di vita di una sessione Studio è la sua creazione. Per iniziare, invia un comando POST all'endpoint Sessions con i seguenti parametri.

Punto finale

Copia

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

Assicurati di includere client_id nell'intestazione della tua richiesta.

Parametri di richiesta

Nome	Descrizione	Tipo di valore / Valori possibili
`Nome`	Nome della sessione	Stringa
`Notification`	`Sì`: l'utente corrente sarà iscritto alle notifiche e-mail sulle modifiche apportate a questa Sessione. `No`: l'utente corrente non sarà iscritto alle notifiche e-mail sulle modifiche apportate a questa Sessione.	Booleano
`Restricted`	`Sì`: limita la Sessione solo agli indirizzi email invitati o aggiunti. `No`: lascia la Sessione Apri a chiunque abbia l'ID sessione di 9 cifre.	Booleano
`SessionEndDate`	Una volta raggiunta questa data, tutti i partecipanti, ad eccezione dell'organizzatore, verranno rimossi dalla sessione.	Must be formatted in UTC format.
`DefaultPermissions`	Questo set di autorizzazioni verrà applicato a tutti gli utenti aggiunti a questa Sessione, ad eccezione dell'host (l'utente corrente). L'host ha il controllo completo.	Di seguito vengono definiti i tipi di autorizzazioni e le autorizzazioni stesse.

Autorizzazione	Descrizione	Tipo di valore / Valori possibili
`Type`	Tipo di permesso	`SaveCopy` : consente ai partecipanti di Salva con nome. `PrintCopy` : consente ai partecipanti di stampare i PDF inclusi nella sessione. `Markup` : consente ai partecipanti di inserire delle Marcature. `AddDocuments` : consente ai partecipanti di aggiungere nuovi documenti alla sessione. `FullControl` : concede ai partecipanti i diritti di amministratore della sessione. `MarkupAlert` – Consente ai partecipanti di inviare e ricevere avvisi di markup durante la Sessione.
`Allow`	Stato di autorizzazione	Consenti, Nega, Predefinito

Autorizzazione

Descrizione

Tipo di valore / Valori possibili

Type

Tipo di permesso

SaveCopy : consente ai partecipanti di Salva con nome.

PrintCopy : consente ai partecipanti di stampare i PDF inclusi nella sessione.

Markup : consente ai partecipanti di inserire delle Marcature.

AddDocuments : consente ai partecipanti di aggiungere nuovi documenti alla sessione.

FullControl : concede ai partecipanti i diritti di amministratore della sessione.

MarkupAlert – Consente ai partecipanti di inviare e ricevere avvisi di markup durante la Sessione.

Allow

Stato di autorizzazione

Consenti, Nega, Predefinito

Data di fine della sessione
Le date di fine sessione non sono obbligatorie, ma se viene selezionata una data di fine sessione, i partecipanti alla sessione saranno avvisati tramite e-mail 7 giorni, 2 giorni e 24 ore prima della data di scadenza.

esempio cURL

Copia

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

Autorizzazioni
Gli attuali utenti di Studio sono spesso abituati a specifiche impostazioni predefinite per le autorizzazioni. È sempre una buona idea controllare quali dovrebbero essere le autorizzazioni predefinite o consentire agli utenti di scegliere le proprie autorizzazioni. Quando si utilizza l'API Bluebeam per impostare le autorizzazioni, il valore predefinito è "Nega".

Corpo di risposta

Copia

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

2. Aggiungi PDF

Il passo successivo è aggiungere i file PDF. L'aggiunta di file è un processo in 3 fasi:

Creazione il blocco metadati per il file tramite l'API Bluebeam
Carica il file direttamente su AWS
Conferma il caricamento tramite l'API Bluebeam

Nota: Sessioni Studio non supporta i file PDF/A.
Poiché PDF/A è un formato di archiviazione, non consente modifiche e causerà il fallimento del passaggio 4 riportato di seguito.

a. Creazione blocco metadati

Punto finale

Copia

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

Parametri

Nome	Descrizione	Tipo di valore / Valori possibili
`Nome`	Nome del file	Stringa che termina con ".pdf"
`Source`	Percorso di origine; questo potrebbe aiutarti a identificare da dove proviene il file più avanti nel processo	Stringa
`Size`	Dimensione del file; lasciare null affinché il server possa calcolarla	Intero
`CRC`	Lascia null affinché il server possa calcolare	Stringa

esempio cURL

Copia

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

Esempio di risposta

Copia

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

Finestra di caricamento
L'URL di caricamento è valido per 10 minuti prima che il caricamento abbia inizio.

c. Conferma il caricamento

Punto finale

Copia

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

esempio cURL

Copia

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

Risposta

In caso di esito positivo, si otterrà una risposta 204 . Per gli errori, vedere i codici di risposta HTML comuni in fondo alla nostra Guida all'autenticazione .

3. Aggiungi utenti

Ora che hai una sessione contenente file PDF, è il momento di aggiungere utenti alla sessione. L'iniziatore della sessione (l'utente corrente) diventa automaticamente l'host della sessione e viene aggiunto automaticamente agli utenti della sessione. È sempre possibile aggiungere altri utenti mentre la sessione è attiva. Esistono 2 metodi per aggiungere utenti:

Metodo A: invita l'utente

Questo metodo è ideale per invitare utenti che potrebbero non avere ancora un account Studio. All'invitato verrà inviata un'e-mail con la possibilità di Creazione un account Studio gratuito.

Punto finale

Copia

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

Parametri

Nome	Descrizione
`Email`	Indirizzo email a cui inviare l'invito

Esempio

Copia

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":"Unisciti a questa Sessione per rivedere i documenti riguardanti l'acquisizione Pied Piper."
    }' \
-X POST

Risposta

In caso di esito positivo, si otterrà una risposta 204 . Per gli errori, vedere i codici di risposta HTML comuni in fondo alla nostra Guida all'autenticazione .

Metodo B: Aggiungi utente

Questo metodo è ideale se sai che l'indirizzo email è già associato a un account Studio e desideri che venga aggiunto a una sessione Studio senza dover esprimere il tuo consenso. Se l'utente non ha un account o non è sicuro di averlo, utilizzare il Metodo A: Invita utente. Utilizzando il Metodo B: Aggiungi utente, l'utente viene aggiunto ai partecipanti alla sessione Studio, e la sessione Studio appare sotto le Sessioni a cui ha partecipato nella Tab Studio dell'interfaccia di Revu.

Punto finale

Copia

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

Parametri

Nome	Descrizione
`Email`	Indirizzo email dell'account Studio noto
`SendEmail`	Booleano; Sì: invia un'e-mail all'invitato, No: non invia una notifica e-mail all'invitato

Esempio

Copia

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": "Come richiesto, ecco la Sessione per accedere ai documenti dell'acquisizione Pied Piper."
    }' \
-X POST

Risposta

In caso di esito positivo, si otterrà una risposta 204 . Per gli errori, vedere i codici di risposta HTML comuni in fondo alla nostra Guida all'autenticazione .

Esempio di email di invito alla sessione

4. Finalizzare la sessione

Per terminare una sessione (operazione che solitamente avviene dopo che i partecipanti hanno terminato di contrassegnare o dopo che è stata raggiunta la data di scadenza della sessione), è necessario modificarne lo stato, gestirne i file e smaltire correttamente la sessione stessa.

a. Set lo stato su Finalizzazione

Impostando lo stato di una Sessione su Finalizzazione, tutti gli utenti vengono rimossi dalla Sessione, ad eccezione dell'host. Ciò viene fatto per impedire ulteriori modifiche ai file di sessione dopo che sono stati scaricati.

Punto finale

Copia

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

Esempio

Copia

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. Scarica i file di sessione contrassegnati

Il download dei file di sessione contrassegnati è un processo in due parti. Seguire i passaggi sottostanti per ogni file nella sessione.

i. Creare una Istantanea

Durante una Sessione, i PDF e le Marcature vengono archiviati separatamente. Una Istantanea combina il contenuto del PDF con il livello di Marcature in un unico PDF, in modo che le Marcature siano visualizzabili sul PDF al di fuori della sessione Studio.

Punto finale

Copia

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

Esempio

Copia

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. Controllare lo stato dell'Istantanea, scaricarla se completa

Effettuare una richiesta GET all'endpoint Istantanea finché lo Status non diventa Complete o Error.

In caso Error: includeremo un messaggio di errore che potrà essere presentato all'utente.
Se Complete: utilizzare DownloadUrl per scaricare l'Istantanea

Punto finale

Copia

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

Esempio

Copia

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

Corpo di risposta

Copia

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

Opzioni di stato

Stato	Descrizione
`NoSnapshot`	Quando un’Istantanea non è mai stata chiamata su un file
`Requested`	Il lavoro Istantanea non è ancora iniziato, ma abbiamo ricevuto la richiesta
`InProgress`	Il lavoro Istantanea è in corso
`Complete`	Il lavoro Istantanea è terminato e può essere scaricato tramite `DownloadUrl`
`Error`	Il processo Istantanea non è riuscito. Lo stato includerà un messaggio di errore.

c. Chiudere la sessione

Ora che hai i PDF contrassegnati, puoi eliminare la sessione inviando una richiesta DELETE all'endpoint ID sessione.

Punto finale

Copia

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

Esempio per chiudere una sessione

Copia

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

Conclusione

Il tipico ciclo di vita di una sessione Studio si completa riportando il file nella sua posizione originale e archiviando la sessione. Sebbene esistano molti modi diversi per lavorare con Sessioni Studio, speriamo che questa guida ti abbia fornito una buona comprensione delle nozioni di base.

Vedi anche:

Risorse

Revu 21

Portale per sviluppatori

Questa guida del Developer Portal tratta del ciclo di vita generale di una Sessione Studio e include esempi di codice.