Gli album creati dalla tua app possono essere condivisi tra utenti, con l'opzione di autorizzarli a inserire commenti o a contribuire all'album con i propri elementi multimediali.
Per condividere un album tramite l'API Raccolta di Google Foto, la tua app deve:
- Creare un album per conto di un utente.
- Imposta l'album come condiviso.
Ambito dell'autenticazione richiesto
Per condividere contenuti, la tua app deve richiedere l'ambito dell'autorizzazione photoslibrary.sharing
.
Condividere un album
Prima di condividere un album, tieni presente quanto segue:
- L'app può condividere soltanto gli album che ha creato. Gli album creati da altre app, incluso Google Foto, non possono essere condivisi dall'app.
- Quando la tua app condivide un album tramite l'API Library, viene generato un URL condivisibile che chiunque può utilizzare per accedere all'album.
- Per gli album condivisi tramite l'API, il proprietario dell'album può disattivare la condivisione tramite link o annullare la condivisione dell'album nell'app Google Foto, impedendo potenzialmente all'app di unirsi a nuovi utenti.
Per condividere un album:
- Segui le linee guida per l'esperienza utente e ottieni il consenso esplicito dell'utente per creare un album condiviso.
- Crea l'album
e registra il relativo
albumId
. Se hai già creato l'album, puoi recuperarnealbumId
inserendo gli album dell'utente. - Chiama
albums.share
utilizzando ilalbumId
pertinente, insieme alle opzioni di condivisione che vuoi impostare. - Registra il valore
shareToken
nella risposta. Il token di condivisione è l'identificatore di un album condiviso, utilizzabile tra diversi account utente. - Un altro utente può ora eseguire l'autenticazione con la tua app, quindi join, abbandonare o recuperare i dettagli dell'album condiviso utilizzando il relativo
shareToken
.
Opzioni di condivisione
Quando condividi un album utilizzando il parametro sharedAlbumOptions
, è possibile impostare le seguenti opzioni. Se le opzioni non sono impostate esplicitamente, vengono utilizzati i valori predefiniti.
Proprietà | Valore predefinito | Descrizione |
---|---|---|
isCollaborative |
false |
Consente di stabilire se altri utenti di Google Foto possono aggiungere contenuti all'album condiviso. |
isCommentable |
false |
Consente di specificare se altri utenti di Google Foto possono commentare l'album condiviso. |
Esempio di richiesta
La seguente richiesta condivide un album chiamando albums.share
con le opzioni. Una
proprietà shareInfo
viene restituita nella risposta che descrive le
proprietà di condivisione dell'album.
REST
Ecco l'intestazione di una richiesta POST per condividere un album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
Nel corpo della richiesta, specifica le opzioni di condivisione.
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
Questa richiesta restituisce la seguente risposta:
{ "shareInfo": { "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" }, "shareableUrl": "shareable-url", "shareToken": "share-token", "isJoinable": "true-if-users-can-join-album", "isJoined": "true-if-user-is-joined-to-album", "isOwned": "true-if-user-owns-album" } }
Java
try { SharedAlbumOptions options = // Set the options for the album you want to share SharedAlbumOptions.newBuilder() .setIsCollaborative(true) .setIsCommentable(true) .build(); ShareAlbumResponse response = photosLibraryClient.shareAlbum(albumId, options); // The response contains the shareInfo object, a url, and a token for sharing ShareInfo info = response.getShareInfo(); // Link to the shared album String url = info.getShareableUrl(); String shareToken = info // The share token which other users of your app can use to join the album you shared .getShareToken(); SharedAlbumOptions sharedOptions = info // The options set when sharing this album .getSharedAlbumOptions(); } catch (ApiException e) { // Handle error }
PHP
// Set the options for the album you want to share $options = new SharedAlbumOptions(); $options->setIsCollaborative(true); $options->setIsCommentable(true); try { $response = $photosLibraryClient->shareAlbum($albumId, ['sharedAlbumOptions' => $options]); // The response contains the shareInfo object, a url, and a token for sharing $shareInfo = $response->getShareInfo(); // Link to the shared album $url = $shareInfo->getShareableUrl(); // The share token which other users of your app can use to join the album you shared $shareToken = $shareInfo->getShareToken(); // The options set when sharing this album $sharedOptions = $shareInfo->getSharedAlbumOptions(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Proprietà album condiviso
Per gli album che sono stati creati e condivisi dalla tua app, tutte le risposte che
restituiscono un elemento album
includono un'ulteriore proprietà,
shareInfo
. Questa proprietà viene restituita in caso di condivisione, elenco o retrieving album.
Nella tabella seguente sono elencate le proprietà shareInfo
:
Proprietà | |
---|---|
sharedAlbumOptions |
Opzioni che indicano se un utente può aggiungere elementi multimediali a un album condiviso o aggiungere commenti. |
shareableUrl |
Un link all'album Google Foto condiviso. Chiunque abbia il link può visualizzare i contenuti dell'album, quindi occorre prestare la massima attenzione. Il campo Un |
shareToken |
Un token che viene utilizzato per join, uscire o recuperare i dettagli di un album condiviso per conto di un utente che non è il proprietario. Un |
isJoinable |
True se gli utenti possono partecipare all'album. |
isJoined |
True se l'utente partecipa all'album. Questo vale sempre per il proprietario dell'album. |
isOwned |
True se l'utente è il proprietario dell'album. |
Annullare la condivisione di un album
Per annullare la condivisione di un album condiviso in precedenza dall'app, chiama albums.unshare
utilizzando albumId
dell'album.
Inoltre, l'album non viene più condiviso, quando si verifica quanto segue:
- Tutti gli utenti che non sono proprietari perderanno l'accesso all'album. Sono incluse le persone che hanno l'album condiviso appositamente con loro tramite l'app Google Foto.
- Tutti i contenuti aggiunti dagli utenti che non sono proprietari saranno rimossi dall'album.
- Se un utente ha precedentemente aggiunto i contenuti dell'album alla propria raccolta, i contenuti verranno conservati nella sua raccolta.
- Il token di condivisione e l'URL condivisibile dell'album verranno invalidati.
Esempio di richiesta
REST
Ecco l'intestazione di una richiesta POST per annullare la condivisione di un album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
Il corpo della richiesta deve essere vuoto.
Se la richiesta ha esito positivo, restituisce una risposta vuota con un codice di stato HTTP di esito positivo. Se la richiesta non ha esito positivo, viene restituito un codice di stato di errore HTTP con un messaggio di errore.
Java
try { // If this call is not successful, an exception is raised photosLibraryClient.unshareAlbum(albumId); } catch (ApiException e) { // Handle error }
PHP
try { // Mark the album as private and no longer shared // If this call is not successful, an exception is raised $photosLibraryClient->unshareAlbum($albumId); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Recupero degli album condivisi e dei token di condivisione
Quando l'app condivide un album, vengono restituiti i dettagli di un album condiviso, incluso il relativo token di condivisione. Puoi anche recuperare questi dettagli in seguito nei seguenti modi.
Se l'utente attualmente connesso alla tua app è il proprietario o fa parte dell'album:
- Con
albums.get
utilizzando ialbumId
pertinenti. - Con
albums.list
, se l'album contiene elementi multimediali. - Con
sharedAlbums.list
, che restituisce tutti gli album condivisi a cui l'utente è membro o di sua proprietà. Per recuperare solo gli album creati dalla tua app, utilizza il parametroexcludeNonAppCreatedData
. - Con
sharedAlbums.get
l'utilizzo di un token di condivisione.
Se l'utente attualmente connesso alla tua app non partecipa all'album, puoi
recuperare i dettagli di un album condiviso con
sharedAlbums.get
utilizzando un
token di condivisione valido.
Esempio di richiesta
REST
Ecco una richiesta per ottenere un album entro il giorno shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Se la richiesta riesce, vengono restituiti i dettagli condivisi
album
.
Java
try { // Get a shared album from its share token Album sharedAlbum = photosLibraryClient.getSharedAlbum(shareToken); String id = sharedAlbum.getId(); String title = sharedAlbum.getTitle(); // ... } catch (ApiException e) { // Handle error }
PHP
try { // Get the album from a share token $album = $photosLibraryClient->getSharedAlbum($shareToken); // Get some properties of an album $productUrl = $album->getProductUrl(); $title = $album->getTitle(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Partecipazione a un album condiviso
La tua app può partecipare a un album condiviso per conto di un utente con il token di condivisione dell'album. Per farlo, le seguenti condizioni devono essere vere:
- L'app ha creato e condiviso l'album.
- L'utente a cui vuoi partecipare non è il proprietario dell'album. In altre parole, il campo
isOwned
nelshareInfo
dell'album è false. - Il token di condivisione sia valido.
- Il campo
isJoinable
nel camposhareInfo
dell'album è true.
REST
Ecco l'intestazione di una richiesta POST per partecipare a un album condiviso:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
Nel corpo della richiesta, specifica shareToken
.
{ "shareToken": "share-token" }
La richiesta POST restituisce il album
condiviso a cui è stata aggiunta l'app per conto dell'utente.
Java
try { // Join the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised JoinSharedAlbumResponse response = photosLibraryClient.joinSharedAlbum(shareToken); Album joinedAlbum = response.getAlbum(); } catch (ApiException e) { // Handle error }
PHP
try { $response = $photosLibraryClient->joinSharedAlbum($shareToken); // Join the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised $joinedAlbum = $response->getAlbum(); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Uscita da un album condiviso
L'app può abbandonare un album condiviso per conto di un utente utilizzando il token di condivisione dell'album. Per farlo, le seguenti condizioni devono essere vere:
- L'app ha creato e condiviso l'album.
- L'utente è attualmente unito all'album. In altre parole, il campo
isJoined
nel camposhareInfo
dell'album è true. - L'utente connesso alla tua app non è il proprietario dell'album. In altre parole, il campo
isOwned
nella sezioneshareInfo
dell'album è false.
REST
Ecco l'intestazione di una richiesta POST per abbandonare un album condiviso:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
Nel corpo della richiesta, specifica shareToken
.
{ "shareToken": "share-token" }
Se la richiesta ha esito positivo, restituisce una risposta vuota con un codice di stato HTTP di esito positivo. Se la richiesta non ha esito positivo, viene restituito un codice di stato di errore HTTP con un messaggio di errore.
Java
try { // Leave a shared album using its share token // If this call is not successful, an exception is raised photosLibraryClient.leaveSharedAlbum(shareToken); } catch (ApiException e) { // Handle error }
PHP
try { // Leave the shared album using the share token obtained when sharing the album // If this call is not successful, an exception is raised $photosLibraryClient->leaveSharedAlbum($shareToken); } catch (\Google\ApiCore\ApiException $e) { // Handle error }
Proprietà degli elementi multimediali condivisi
Gli elementi multimediali appartenenti agli album condivisi dalla tua app contengono una proprietà aggiuntiva, contributorInfo
.
Questa proprietà è inclusa solo quando elenchi i
contenuti di un album condiviso.
La proprietà contributorInfo
include il nome dell'utente che ha aggiunto l'elemento
multimediale all'album e un
URL di base all'immagine
del suo profilo.
Esempio:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }