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

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

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

  1. Создайте альбом от имени пользователя.
  2. Установите для этого альбома общий статус .

Требуемая область аутентификации

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

Публикация альбома

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

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

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

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

Варианты обмена

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

Свойство Значение по умолчанию Описание
isCollaborative false Определяет, могут ли другие пользователи Google Фото добавлять контент в общий альбом.
isCommentable false Определяет, могут ли другие пользователи Google Фото комментировать общий альбом.

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

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

ОТДЫХЯва PHP

Вот заголовок запроса POST, чтобы поделиться альбомом:

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 :

Характеристики
sharedAlbumOptions Параметры, которые определяют, может ли кто-либо добавлять мультимедийные элементы в общий альбом или комментировать его .
shareableUrl

Ссылка на общий альбом Google Фото. Содержимое альбома может просмотреть любой, у кого есть ссылка, поэтому к нему следует относиться осторожно.

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

shareableUrl становится недействительным, если владелец отключает общий доступ по ссылке в приложении Google Фото или если доступ к альбому закрыт.

shareToken

Токен, который используется для присоединения , выхода из общего альбома или получения сведений об общем альбоме от имени пользователя, не являющегося владельцем.

shareToken становится недействительным, если владелец отключает общий доступ по ссылке в приложении Google Фото или если доступ к альбому закрыт.

isJoinable True , если пользователи могут присоединиться к альбому.
isJoined True , если пользователь присоединился к альбому. Это всегда справедливо для владельца альбома.
isOwned True , если альбом принадлежит пользователю.

Отключение общего доступа к альбому

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

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

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

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

ОТДЫХ Ява PHP

Вот заголовок запроса POST, чтобы отменить общий доступ к альбому:

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

Тело запроса должно быть пустым.

Если запрос был успешным, он возвращает пустой ответ с кодом состояния успеха HTTP. Если запрос не был успешным, он возвращает код состояния ошибки HTTP с сообщением об ошибке. 

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 используя действительный токен общего доступа.

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

ОТДЫХ Ява PHP

Вот запрос на получение альбома по его shareToken :

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

Если запрос успешен, он возвращает сведения об общем album . 

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.
ОТДЫХ Ява PHP

Вот заголовок запроса POST для присоединения к общему альбому:

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

В теле запроса укажите shareToken .

{
  "shareToken": "share-token"
}

Запрос POST возвращает общий album , к которому ваше приложение присоединилось от имени пользователя. 

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.
ОТДЫХ Ява PHP

Вот заголовок запроса POST, чтобы покинуть общий альбом:

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

В теле запроса укажите shareToken .

{
  "shareToken": "share-token"
}

Если запрос был успешным, он возвращает пустой ответ с кодом состояния успеха HTTP. Если запрос не был успешным, он возвращает код состояния ошибки HTTP с сообщением об ошибке. 

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