Les albums créés par votre application peuvent être partagés entre les utilisateurs, avec des options permettant à ces utilisateurs de commenter ou d'ajouter leurs propres éléments multimédias à l'album.
Pour partager un album via l'API Library de Google Photos, votre application doit procéder comme suit:
- Créez un album au nom d'un utilisateur.
- Vous pouvez partager cet album.
Champ d'application d'authentification requis
Pour partager du contenu, votre application doit demander le champ d'application des autorisations photoslibrary.sharing
.
Partager un album
Avant de partager un album, tenez compte des points suivants:
- Votre application ne peut partager que les albums qu'elle a créés. Les albums créés par d'autres applications, y compris Google Photos, ne peuvent pas être partagés par votre application.
- Lorsque votre application partage un album via l'API Library, une URL partageable est générée. Tout le monde peut l'utiliser pour y accéder.
- Pour les albums partagés via l'API, le propriétaire de l'album peut désactiver le partage par lien ou annuler le partage de l'album dans l'application Google Photos, ce qui peut empêcher votre application de rejoindre de nouveaux utilisateurs.
Pour partager un album:
- Suivez les consignes relatives à l'expérience utilisateur et obtenez le consentement explicite de l'utilisateur pour créer un album partagé.
- Créez l'album et enregistrez son
albumId
. Si vous avez déjà créé l'album, vous pouvez récupérer sonalbumId
en répertoriant les albums de l'utilisateur. - Appelez
albums.share
à l'aide dualbumId
approprié, ainsi que des options de partage que vous souhaitez définir. - Enregistrez la valeur
shareToken
dans la réponse. Le jeton de partage est un identifiant pour un album partagé qui peut être utilisé sur différents comptes utilisateur. - Un autre utilisateur peut maintenant s'authentifier auprès de votre application, puis join, quitter ou récupérer les détails de l'album partagé à l'aide de son
shareToken
.
Options de partage
Les options suivantes peuvent être définies lors du partage d'un album à l'aide du paramètre sharedAlbumOptions
. Si les options ne sont pas définies explicitement, les valeurs par défaut sont utilisées.
Propriété | Valeur par défaut | Description |
---|---|---|
isCollaborative |
false |
Détermine si d'autres utilisateurs de Google Photos peuvent ajouter du contenu à l'album partagé. |
isCommentable |
false |
Détermine si les autres utilisateurs de Google Photos peuvent commenter l'album partagé. |
Exemple de requête
La requête suivante permet de partager un album en appelant albums.share
avec des options. Une propriété shareInfo
est renvoyée dans la réponse décrivant les propriétés de partage de l'album.
REST
Voici un en-tête de requête POST permettant de partager un album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
Dans le corps de la requête, spécifiez les options de partage.
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
Cette requête renvoie la réponse suivante:
{ "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 }
Propriétés des albums partagés
Pour les albums créés et partagés par votre application, toutes les réponses qui renvoient un album
incluent une propriété supplémentaire, shareInfo
. Cette propriété est renvoyée lors du partage, de la création d'une liste ou de la retrieving des albums.
Le tableau suivant répertorie les propriétés de shareInfo
:
Propriétés | |
---|---|
sharedAlbumOptions |
Options indiquant si un utilisateur peut ajouter des éléments multimédias à un album partagé ou commenter un album partagé. |
shareableUrl |
Lien vers l'album Google Photos partagé. Toutes les personnes disposant du lien peuvent afficher le contenu de l'album. Vous devez donc l'utiliser avec précaution. Le champ Une |
shareToken |
Jeton utilisé pour join, quitter ou récupérer les détails d'un album partagé au nom d'un utilisateur qui n'en est pas le propriétaire. Une |
isJoinable |
True si l'album peut être rejoint par des utilisateurs. |
isJoined |
True si l'utilisateur est membre de l'album Cela est toujours vrai pour le propriétaire d'un album. |
isOwned |
True si l'utilisateur est le propriétaire de l'album |
Annuler le partage d'un album
Pour annuler le partage d'un album partagé par votre application, appelez albums.unshare
à l'aide du albumId
de l'album.
L'album n'est plus partagé. Conséquences:
- Tous les utilisateurs qui ne sont pas propriétaires n'y auront plus accès. y compris les personnes qui ont partagé l'album spécifiquement avec elles via l'application Google Photos.
- Tous les contenus ajoutés par des non-propriétaires sont supprimés de l'album.
- Si un utilisateur a déjà ajouté le contenu de l'album à sa bibliothèque, le contenu y sera conservé.
- Le jeton de partage et l'URL partageable de l'album ne seront plus valides.
Exemple de requête
REST
Voici un en-tête de requête POST permettant d'annuler le partage d'un album:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
Le corps de la requête doit être vide.
Si la requête a abouti, il renvoie une réponse vide avec un code d'état HTTP de réussite. Si la requête n'a pas abouti, il renvoie un code d'état d'erreur HTTP avec un message d'erreur.
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 }
Récupérer des albums partagés et des jetons de partage
Les détails d'un album partagé, y compris son jeton de partage, sont renvoyés lorsque votre application partage un album. Vous pouvez également récupérer ces informations par la suite de différentes manières.
Si l'utilisateur actuellement connecté à votre application en est le propriétaire ou a rejoint l'album:
- Avec
albums.get
utilisant lealbumId
approprié. - Avec
albums.list
, si l'album contient des éléments multimédias - Avec
sharedAlbums.list
, qui renvoie tous les albums partagés auxquels l'utilisateur est associé ou qu'il possède Pour récupérer uniquement les albums créés par votre application, utilisez le paramètreexcludeNonAppCreatedData
. - Avec
sharedAlbums.get
utilisant un jeton de partage.
Si l'utilisateur actuellement connecté à votre application n'est pas membre de l'album, vous pouvez récupérer les détails d'un album partagé avec sharedAlbums.get
à l'aide d'un jeton de partage valide.
Exemple de requête
REST
Voici une requête permettant de récupérer un album en fonction de son shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Si la requête aboutit, les détails partagés de
album
sont renvoyés.
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 }
Rejoindre un album partagé
Votre application peut rejoindre un album partagé au nom d'un utilisateur avec le jeton de partage de l'album. Pour ce faire, les conditions suivantes doivent être remplies:
- Votre application a créé et partagé l'album.
- L'utilisateur que vous voulez associer à l'album n'en est pas le propriétaire. Autrement dit, le champ
isOwned
du fichiershareInfo
de l'album est "false". - Le jeton de partage est valide.
- La valeur du champ
isJoinable
du fichiershareInfo
de l'album est "true".
REST
Voici un en-tête de requête POST visant à rejoindre un album partagé:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
Dans le corps de la requête, spécifiez shareToken
.
{ "shareToken": "share-token" }
La requête POST renvoie le album
partagé que votre application a joint au nom de l'utilisateur.
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 }
Sortie d'un album partagé
Votre application peut quitter un album partagé au nom d'un utilisateur à l'aide du jeton de partage de l'album. Pour ce faire, les conditions suivantes doivent être remplies:
- Votre application a créé et partagé l'album.
- L'utilisateur est actuellement joint à l'album. Autrement dit, le champ
isJoined
du champshareInfo
de l'album est défini sur "true". - L'utilisateur connecté à votre application n'est pas le propriétaire de l'album. Autrement dit, le champ
isOwned
du fichiershareInfo
de l'album est "false".
REST
Voici un en-tête de requête POST permettant de quitter un album partagé:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
Dans le corps de la requête, spécifiez shareToken
.
{ "shareToken": "share-token" }
Si la requête a abouti, il renvoie une réponse vide avec un code d'état HTTP de réussite. Si la requête n'a pas abouti, il renvoie un code d'état d'erreur HTTP avec un message d'erreur.
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 }
Propriétés des éléments multimédias partagés
Les éléments multimédias appartenant aux albums partagés par votre application contiennent une propriété supplémentaire, contributorInfo
.
Cette propriété n'est incluse que lorsque vous listez le contenu d'un album partagé.
La propriété contributorInfo
inclut le nom de l'utilisateur qui a ajouté l'élément multimédia à l'album et une URL de base à son image de profil.
Exemple :
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }