Поделиться медиаконтентом

Альбомами, созданными в вашем приложении, можно делиться с другими пользователями, разрешая им оставлять комментарии или добавлять в альбом свои мультимедийные объекты.

Чтобы поделиться альбомом через Google Photos Library API, ваше приложение должно выполнить следующие действия:

1. Создавать альбомы от имени пользователя.
2. Откройте доступ к альбому.

Область аутентификации

Чтобы делиться контентом, приложение должно запросить область авторизации photoslibrary.sharing.

Как поделиться альбомом

Прежде чем поделиться альбомом, учтите следующее:

• Приложение может делиться только теми альбомами, которые оно создало. Альбомы, созданные другими приложениями, в том числе Google Фото, не могут быть предоставлены вашим приложением.
• Когда ваше приложение делится альбомом через Library API, генерируется URL для доступа, по которому любой пользователь может открыть альбом.
• Владелец альбома, которым поделились через API, может отключить доступ по ссылке или закрыть доступ к альбому в приложении "Google Фото". В результате ваше приложение не сможет добавлять в альбом новых пользователей.

Чтобы поделиться альбомом:

1. Следуйте рекомендациям по UX и получите явное согласие пользователя на создание общего альбома.
2. Создайте альбом и запишите его albumId. Если вы уже создали альбом, вы можете получить его albumId, составив список альбомов пользователя.
3. Вызовите albums.share, используя нужный albumId и задав параметры доступа.
4. Запишите значение shareToken в ответе. Токен общего доступа – это идентификатор общего альбома, который можно использовать в разных аккаунтах пользователей.
5. Теперь другой пользователь может выполнить аутентификацию в вашем приложении, а затем присоединиться к общему альбому, покинуть его или получить сведения о нем, используя его shareToken.

Настройки доступа

При предоставлении доступа к альбому с помощью параметра sharedAlbumOptions можно задать следующие настройки: Если параметры не заданы явно, используются значения по умолчанию.

Пример запроса

В следующем запросе альбом предоставляется путем вызова albums.share с параметрами. В ответе возвращается свойство shareInfo, описывающее свойства доступа к альбому.

POST https://photoslibrary.googleapis.com/v1/albums/album-id:share
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "sharedAlbumOptions": {
    "isCollaborative": "true",
    "isCommentable": "true"
  }
}

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

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
}

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

Свойства общего альбома

Для альбомов, созданных и опубликованных вашим приложением, все ответы, возвращающие album, включают дополнительное свойство shareInfo. Это свойство возвращается при предоставлении доступа к альбомам, их перечислении или получении.

В таблице ниже перечислены свойства shareInfo.

Вы закрываете доступ к альбому

Чтобы закрыть доступ к альбому, который ранее был опубликован через ваше приложение, вызовите метод albums.unshare, используя albumId альбома.

Помимо того, что альбом перестанет быть общим, произойдет следующее:

• Все, кроме владельца, потеряют доступ к альбому. Это относится и к тем, кому вы открыли доступ к альбому через приложение "Google Фото".
• Весь контент, добавленный другими пользователями, будет удален из альбома.
• Если пользователь ранее добавил содержимое альбома в свою библиотеку, оно останется в ней.
• Токен и URL для доступа к альбому станут недействительными.

Пример запроса

POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare
Content-type: application/json
Authorization: Bearer oauth2-token

try {
  // If this call is not successful, an exception is raised
  photosLibraryClient.unshareAlbum(albumId);
} catch (ApiException e) {
  // Handle error
}

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
}

Получение общих альбомов и токенов доступа

Сведения об общем альбоме, включая его токен доступа, возвращаются, когда ваше приложение делится альбомом. Вы также можете получить эти данные позже, выполнив следующие действия.

Если пользователь, подключенный к вашему приложению, является владельцем или присоединился к альбому:

• С помощью albums.get, используя соответствующий albumId.
• С albums.list, если в альбоме есть мультимедийные объекты.
• С помощью метода sharedAlbums.list, который возвращает все общие альбомы, к которым присоединился пользователь или которыми он владеет. Чтобы получить только альбомы, созданные вашим приложением, используйте параметр excludeNonAppCreatedData.
• С помощью sharedAlbums.get, используя токен доступа.

Если пользователь, подключенный к вашему приложению, не присоединился к альбому, вы можете получить сведения об общем альбоме с помощью метода sharedAlbums.get, используя действительный токен доступа.

Пример запроса

GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token

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
}

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
}

Как присоединиться к общему альбому

Ваше приложение может присоединиться к общему альбому от имени пользователя с помощью токена доступа к альбому. Для этого должны выполняться следующие условия:

• Ваше приложение создало альбом и поделилось им.
• Пользователь, которого вы хотите добавить в альбом, не является его владельцем. Это означает, что поле isOwned в объекте shareInfo альбома имеет значение false.
• Токен действителен.
• Поле isJoinable в файле shareInfo альбома имеет значение true.

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "shareToken": "share-token"
}

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
}

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
}

Как покинуть общий альбом

Ваше приложение может покинуть общий альбом от имени пользователя, используя токен доступа к альбому. Для этого должны выполняться следующие условия:

• Приложение создало альбом и поделилось им.
• Пользователь уже присоединился к альбому. То есть поле isJoined в объекте shareInfo альбома имеет значение true.
• Пользователь, подключенный к вашему приложению, не является владельцем альбома. Это означает, что в поле isOwned в shareInfo альбома указано значение false.

POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave
Content-type: application/json
Authorization: Bearer oauth2-token

{
  "shareToken": "share-token"
}

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
}

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
}

Свойства общих медиаобъектов

Мультимедийные объекты, которые принадлежат альбомам, доступ к которым предоставлен вашим приложением, содержат дополнительное свойство contributorInfo. Это свойство включается только при перечислении содержимого общего альбома.

Свойство contributorInfo содержит имя пользователя, который добавил мультимедийный объект в альбом, и базовый URL его фото профиля.

Пример:

{
  "id: "media-item-id",
  ...,
  "mediaMetadata": {
    ...
  }
  "contributorInfo": {
    "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters",
    "displayName": "name-of-user"
  }
}