Partager le contenu multimédia

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:

1. Créez un album au nom d'un utilisateur.
2. Vous pouvez partager cet album.

Remarque :Avant de partager un album, obtenez le consentement explicite de l'utilisateur et assurez-vous de suivre les consignes relatives à l'expérience utilisateur.

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:

1. Suivez les consignes relatives à l'expérience utilisateur et obtenez le consentement explicite de l'utilisateur pour créer un album partagé.
2. Créez l'album et enregistrez son albumId. Si vous avez déjà créé l'album, vous pouvez récupérer son albumId en répertoriant les albums de l'utilisateur.
3. Appelez albums.share à l'aide du albumId approprié, ainsi que des options de partage que vous souhaitez définir.
4. 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.
5. 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 shareableUrl n'est renvoyé que si le partage par lien est activé pour l'album. Si un utilisateur est déjà associé à un album qui n'est pas partagé par lien, il peut utiliser l'productUrl de l'album pour y accéder. Une shareableUrl n'est plus valide si le propriétaire désactive le partage par lien dans l'application Google Photos ou si le partage de l'album n'est pas activé.
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 shareToken n'est plus valide si le propriétaire désactive le partage par lien dans l'application Google Photos ou si le partage de l'album n'est pas activé.
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

Attention :Toute personne disposant du shareableUrl d'un album peut en afficher le contenu.

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 le albumId 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ètre excludeNonAppCreatedData.
• 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 fichier shareInfo de l'album est "false".
• Le jeton de partage est valide.
• La valeur du champ isJoinable du fichier shareInfo de l'album est "true".

Attention :Une fois que votre application a partagé un album, son propriétaire peut désactiver le partage par lien ou annuler le partage de l'album dans l'application Google Photos. Dans ce cas, le jeton de partage de l'album n'est plus valide, son champ isJoinable devient "false", et votre application ne peut pas y joindre les utilisateurs.

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 champ shareInfo 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 fichier shareInfo 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"
  }
}

Remarque :La propriété contributorInfo n'est renvoyée que si l'utilisateur a accordé l'accès au champ d'application photoslibrary.sharing.