Guide till Studio-sessioner

Bluebeam Developer Portal, för utveckling av integrationer, är endast tillgänglig för aktiva kunder, kanalpartners och programvarupartners i regionerna USA, AU, DE, UK och SE.

Se en Studio-session som ett digitalt konferensrum där PDF-ritningar kan markeras antingen samtidigt eller asynkront. Den här guiden omfattar den allmänna livscykeln för en Studio-session och innehåller kodexempel. Om du vill veta mer om Studio- och Studio-sessioner i allmänhet kan du gå till vår sida med vanliga frågor om Studio.

Du kan följa med i den här guiden och prova många av de anrop som finns i Studio-avsnittet i våra API-dokument. Se vår guide Kom igång med Bluebeam Developer Portal för instruktioner om hur du skaffar en giltig åtkomsttoken.

Det finns regionspecifika bas-URL:er som gäller för alla slutpunkter:

- 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

Till exempel blir https://api.bluebeam.com/publicapi/v1/sessions i regionen US https://api.bluebeamstudio.com.au/publicapi/v1/sessions i regionen AU.

Studio-sessioners livscykel

Livscykeln för en Studio-session kan delas upp i fyra delar:

  1. Initiering – öppnar upp det ”digitala konferensrummet”

  2. Lägg till PDF-filer i sessionen för visning och markeringar

  3. Lägg till användare i sessionen så att de kan visa och markera

  4. Slutförande – Stänger sessionen och returnerar de markerade PDF-filerna till sina ursprungliga system

Den första fasen i livscykeln för en Studio-session är att den skapas. Börja med att skicka ett POST-kommando till sessionens slutpunkt med följande parametrar.

Slutpunkt

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

Ange client_id i rubriken på din förfrågan.

Begär parametrar

Namn

Beskrivning

Värdetyp/möjliga värden

Namn

Sessionsnamn

Sträng

Notification

true: Nuvarande användare prenumererar på e-postaviseringar om ändringar i den här sessionen.

false: Nuvarande användare prenumererar inte på e-postaviseringar om ändringar i den här sessionen.

Boolean

Restricted

true: Begränsar sessionen till enbart e-postadresser som har bjudits in eller lagts till.

false: Låter sessionen vara öppen för alla som har det niosiffriga sessions-ID:t.

Boolean

SessionEndDate

När detta datum har nåtts kommer alla deltagare utom värden att tas bort från sessionen.

Måste vara formaterat i UTC-format.

DefaultPermissions

Den här behörighetsuppsättningen gäller för alla användare som läggs till i sessionen utom värden (den aktuella användaren). Värden får full kontroll.

Nedan anger du typer av behörigheter och själva behörigheterna.

Behörighet

Beskrivning

Värdetyp/möjliga värden

Type

Typ av behörighet

SaveCopy – Tillåt deltagare att spara som.

PrintCopy – Tillåt deltagare att skriva ut PDF-filer som ingår i sessionen.

Markering – Tillåt deltagarna att placera ut markeringar.

Lägg till dokument – Gör att deltagarna kan lägga till nya dokument i sessionen.

FullControl – Ge deltagarna administratörsrättigheter till sessionen.

MarkupAlert – Tillåt deltagare att skicka och ta emot markeringsaviseringar under sessionen.

Allow

Behörighetsläge

Tillåt, Neka, Standard

Slutdatum för session
Slutdatum för sessioner krävs inget, men om du har valt ett slutdatum för sessionen meddelas deltagare till sessionen per e-post 7 dagar, 2 dagar och 24 timmar före utgångsdatumet.

exempel på 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

Behörigheter
Nuvarande Studio-användare är ofta vana vid specifika standardinställningar för behörigheter. Det är alltid en bra idé att antingen kontrollera vilka standardrättigheterna ska vara eller låta användarna välja sina behörigheter. När du använder Bluebeam API för att ställa in behörigheter är Neka standardvärdet.

Brödtext för svar

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

Nästa steg är att lägga till PDF-filerna. Processen för att lägga till filer sker i tre steg:

  1. Skapa metadatablocket för filen via Bluebeams API

  2. Ladda upp filen direkt till AWS

  3. Bekräfta uppladdning via Bluebeam API

Obs! Studio-sessioner har inte stöd för PDF/A-filer.
Eftersom PDF/A är ett arkiveringsformat går det inte att redigera, vilket gör att steg 4 nedan misslyckas.

Slutpunkt

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

Parametrar

Namn

Beskrivning

Värdetyp/möjliga värden

Namn

Namn på fil

Sträng som slutar på .pdf

Source

Källsökväg; Det kan hjälpa dig att ta reda på var filen kommer ifrån senare i processen

Sträng

Size

Filstorlek; lämna null för servern att beräkna

Heltal

CRC

Lämna null om du vill beräkna servern

Sträng

exempel på 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

Exempel på svar

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

Fönstret Uppladdning
URL för uppladdning gäller i 10 minuter för att starta uppladdning.

När du har en platshållare för metadatablock för filen gör du en PUT-begäran till den returnerade uppladdnings-URL från den tidigare POST-begäran. Inkludera följande i rubriken i din PUT-förfrågan:

  • "x-amz-server-side-encryption" med värde "AES256"

  • "Content-Type" med värde "application/pdf"

Slutpunkt

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

exempel på 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

Svar

Lyckas du får du 204-svar. För fel, se de vanligaste svarskoderna i HTML längst ner i vår autentiseringsguide.

 

Nu när du har en session med PDF-filer är det dags att lägga till användare i sessionen. Den som leder sessionen (den nuvarande användaren) blir automatiskt sessionsvärd och läggs automatiskt till bland sessionens användare. Fler användare kan alltid läggas till medan sessionen är aktiv. Det finns två metoder för att lägga till användare:

Den här metoden fungerar bäst om du vill bjuda in användare som kanske inte har ett Studio-konto ännu. Ett e-postmeddelande skickas till den inbjudna personen om en möjlighet att skapa ett kostnadsfritt Studio-konto.

Slutpunkt

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

Parametrar

Namn

Beskrivning

Email

E-postadress att skicka inbjudan till

Meddelande

Anpassat meddelande som visas i e-postmeddelandet

Exempel

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":"Please join this Session to review documents regarding the Pied Piper acquisition."
    }' \
-X POST

Svar

Lyckas du får du 204-svar. För fel, se de vanligaste svarskoderna i HTML längst ner i vår autentiseringsguide.

OR

Den här metoden fungerar bäst om du vet att e-postadressen redan är kopplad till ett Studio-konto och du vill att kontot ska läggas till i en Studio-session utan att delta. Om användaren inte har ett konto, eller om hen är osäkra på om man har, använder metod A: Bjud in användare. Med metod B: Lägg till användare läggs till användaren bland Studio-sessionens deltagare och Studio-sessionen visas under deras Deltagare i sessioner på fliken Studio i gränssnittet i Revu.

Slutpunkt

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

Parametrar

Namn

Beskrivning

Email

E-postadressen för det kända Studio-kontot

SendEmail

Boolean; Sant: Skicka ett e-postmeddelande till den inbjudna personen, Falskt: Skicka inget e-postmeddelande till den inbjudna personen

Meddelande

Anpassat meddelande som visas i e-postmeddelandet

Exempel

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": "As requested, here is the Session to review the Pied Piper acquisition documents."
    }' \
-X POST

Svar

Lyckas du får du 204-svar. För fel, se de vanligaste svarskoderna i HTML längst ner i vår autentiseringsguide.

Exempel på e-postinbjudan till session

 

För att avsluta en session (görs vanligtvis efter att deltagarna har markerat färdigt eller sessionens utgångsdatum har nåtts) måste dess status ändras, dess filer måste hanteras, och själva sessionen måste kasseras på rätt sätt.

Om du ställer in en sessions status på Slutför tas alla användare utom värden bort från sessionen. Det här görs för att förhindra ytterligare ändringar i sessionsfilerna efter att de har laddats ner.

Slutpunkt

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

Exempel

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

Nedladdningen av de markerade sessionsfilerna består av två delar. Följ stegen nedan för varje fil i sessionen.

i. Skapa en ögonblicksbild

PDF-filer och markeringar i en session lagras separat. En ögonblicksbild kombinerar PDF-innehållet med markeringslagret till en enda PDF-fil, så att markeringarna kan visas i PDF-filen utanför Studio-sessionen.

Slutpunkt

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

Exempel

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. Kontrollera status för ögonblicksbild, ladda ner den om den är slutförd

Skicka en GET-begäran till slutpunkten för ögonblicksbilden tills statusen är antingen Complete eller Error.

  • Om fel: Vi inkluderar ett felmeddelande som kan visas för användaren.

  • Om Complete: Använd URL:en för nedladdning för att ladda ner ögonblicksbilden

Slutpunkt

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

Exempel

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

Brödtext för svar

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

Statusalternativ

Status

Beskrivning

NoSnapshot

När en ögonblicksbild aldrig har använts för en fil

Requested

Ögonblicksbilden har ännu inte påbörjats, men vi tog emot förfrågan

InProgress

En ögonblicksbild pågår

Complete

Ögonblicksbildsjobbet är slutfört och kan laddas ner via Ladda nerUrl

Error

Ögonblicksbilden misslyckades. Statusen innehåller ett felmeddelande.

Nu när du har de markerade PDF-filerna kan du förfoga över sessionen genom att skicka en DELETE-begäran till slutpunkten för sessions-ID.

Slutpunkt

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

Exempel på att stänga en 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

 

Slutsatser

Att returnera filen till sin ursprungliga plats och arkivera sessionen slutför den typiska livscykeln för Studio-sessionen. Även om det finns många olika sätt att arbeta med Studio-sessioner hoppas vi att den här genomgången har gett dig en bra förståelse av grunderna.

 

Se även:

Resurser

Revu 21

Utvecklarportalen

Utvecklarportalen

I den här guiden till Developer Portal beskrivs den allmänna livscykeln för en Studio-session tillsammans med kodexempel.