分享媒體

使用者可共用應用程式建立的相簿，且可選擇允許使用者在相簿中留言或提供自己的媒體項目。

如要透過 Google Photos Library API 共享相簿，應用程式必須執行下列步驟：

  1. 代表使用者建立相簿。
  2. 將相簿設為共享。

必要的驗證範圍

您的應用程式必須要求 photoslibrary.sharing 授權範圍，才能分享內容。

分享相簿

共享相簿前，請考量下列事項：

  • 應用程式只能分享自己建立的相簿。應用程式無法分享由其他應用程式 (包括 Google 相簿) 建立的相簿。
  • 應用程式透過 Library API 分享專輯時，會產生可分享網址，以供任何人存取該專輯。
  • 如果是透過 API 共享的相簿，相簿擁有者可以關閉連結共享設定，或是取消 Google 相簿應用程式中的相簿分享功能，這可能會導致應用程式無法加入新使用者。

如何分享相簿：

  1. 請遵循使用者體驗指南，取得使用者明確同意來建立共享相簿。
  2. 建立相簿，並錄製其 albumId。如果您已建立相簿，可以列出使用者的相簿，以擷取其 albumId。
  3. 使用相關的 albumId 呼叫 albums.share，以及您要設定的共用選項。
  4. 記錄回應中的 shareToken 值。共用權杖是共用相簿的 ID，可在不同的使用者帳戶中使用。
  5. 現在其他使用者可以透過您的應用程式進行驗證，然後使用其 shareToken join、離開或擷取共享相簿的詳細資料。

分享選項

使用 sharedAlbumOptions 參數共享相簿時，您可以設定下列選項。如果選項未明確設定，系統會使用預設值。
屬性 預設值 說明
isCollaborative false 設定是否允許其他 Google 相簿使用者可以在共享相簿中新增內容。
isCommentable false 設定是否允許其他 Google 相簿使用者在共享相簿中發表留言。

要求範例

以下要求透過呼叫 albums.share 的方式分享相簿，並提供選項。回應中會傳回 shareInfo 屬性，說明相簿的分享屬性。

REST

以下是分享相簿的 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"
  }
}

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
}

共享相簿屬性

對於已經建立並分享的相簿，所有傳回 album 的回應都會包含額外屬性 shareInfo。分享、列出或retrieving相簿時，系統會傳回這個屬性。

下表列出 shareInfo 屬性：

屬性
sharedAlbumOptions 說明使用者是否可以在共享相簿中新增媒體項目或發表留言。
shareableUrl

共享 Google 相簿的連結。知道連結的人都能查看相簿內容，因此請謹慎處理。

只有在相簿已開啟連結共享功能時，系統才會傳回 shareableUrl 欄位。如果使用者已加入未透過連結分享的相簿，可以改用相簿的 productUrl 存取。

如果擁有者關閉 Google 相簿應用程式中的連結共享設定，或是相簿已取消分享，shareableUrl 就會失效。
shareToken

這類權杖可用來代表非擁有者使用者join、離開或擷取共享相簿的詳細資料。

如果擁有者關閉 Google 相簿應用程式中的連結共享設定，或是相簿已取消分享，shareToken 就會失效。
isJoinable True (表示使用者可加入相簿)。
isJoined True (如果使用者已加入相簿)。該日期對相簿擁有者來說皆是如此。
isOwned True (如果是使用者擁有的相簿)。

取消共享相簿

如要取消分享應用程式先前分享的相簿，請使用相簿的 albumId 呼叫 albums.unshare。

除了停止共享相簿外，還會發生下列情況：

  • 所有非擁有者的使用者都將無法再存取相簿。這包括透過 Google 相簿應用程式特定共享相簿的使用者。
  • 所有由非擁有者新增的內容都會從相簿中移除。
  • 如果使用者先前已將專輯內容新增至媒體庫，這些內容會保留在他們的媒體庫中。
  • 相簿的分享權杖和可分享的網址將會失效。

要求範例

REST

以下是取消分享相簿的 POST 要求標頭：

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

要求主體必須為空白。

如果要求成功，系統會傳回包含 HTTP 成功狀態碼的空白回應。如果要求失敗，則會傳回含有錯誤訊息的 HTTP 錯誤狀態碼。

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
}

擷取共用相簿及分享權杖

應用程式分享相簿時，系統會傳回共享相簿的詳細資料 (包括共用權杖)。之後，您也可以透過下列方式擷取這些詳細資料。

如果目前連線至應用程式的使用者為擁有者或已加入相簿：

如果目前連線至應用程式的使用者尚未加入相簿，您可以使用有效的共用權杖，透過 sharedAlbums.get 擷取共享相簿的詳細資料。

要求範例

REST

以下要求在 shareToken 前取得專輯：

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

如果要求成功，系統會傳回共用的 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
}

正在加入共享相簿

應用程式可使用相簿的分享權杖，代表使用者加入共享相簿。前提是必須符合下列條件：

  • 應用程式建立並分享該相簿。
  • 你要加入相簿的使用者不是擁有者。也就是說，相簿的 shareInfo 中的 isOwned 欄位為 false。
  • 共用權杖有效。
  • 專輯 shareInfo 中的 isJoinable 欄位為 true。

REST

以下是加入共享相簿的 POST 要求標頭：

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

在要求主體中，指定 shareToken。

{
  "shareToken": "share-token"
}

POST 要求會傳回共用的 album，您的應用程式會代表使用者加入。

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
}

正在離開共享相簿

應用程式可使用相簿的分享權杖，代表使用者離開共享相簿。前提是必須符合下列條件：

  • 應用程式已建立並分享了這本相簿。
  • 使用者目前已加入相簿。也就是說，相簿的 shareInfo 中的 isJoined 欄位為 true。
  • 連結至應用程式的使用者不是相簿擁有者。也就是說，相簿 shareInfo 中的 isOwned 欄位為 false。

REST

以下是離開共享相簿的 POST 要求標頭：

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

在要求主體中，指定 shareToken。

{
  "shareToken": "share-token"
}

如果要求成功，系統會傳回包含 HTTP 成功狀態碼的空白回應。如果要求失敗，則會傳回含有錯誤訊息的 HTTP 錯誤狀態碼。

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
}

共用媒體項目屬性

應用程式所分享相簿的媒體項目包含額外屬性 contributorInfo。只有在列出共享相簿內容時，才會納入這個屬性。

contributorInfo 屬性包含將媒體項目新增至相簿的使用者名稱，以及新增至個人資料圖片的基本網址。

範例如下：

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