Udostępnij multimedia

Albumy utworzone w Twojej aplikacji mogą być udostępniane między użytkownikami. Użytkownicy będą mogli na przykład zezwolić im na komentowanie lub dodawanie własnych elementów multimedialnych do albumu.

Aby udostępnić album za pomocą interfejsu API biblioteki Zdjęć Google, aplikacja musi:

1. utworzyć album w imieniu użytkownika;
2. Ustaw album jako udostępniony.

Uwaga: zanim udostępnisz album, uzyskaj wyraźną zgodę użytkownika i postępuj zgodnie z wytycznymi dotyczącymi UX.

Wymagany zakres uwierzytelniania

Aby udostępniać treści, aplikacja musi zażądać zakresu autoryzacji photoslibrary.sharing.

Udostępnianie albumu

Zanim udostępnisz album, weź pod uwagę te kwestie:

• Aplikacja może udostępniać tylko albumy utworzone przez siebie. Aplikacja nie może udostępniać albumów utworzonych przez inne aplikacje, w tym Zdjęcia Google.
• Gdy aplikacja udostępni album za pomocą interfejsu Library API, generowany jest adres URL do udostępniania, za pomocą którego każdy może uzyskać dostęp do albumu.
• W przypadku albumów udostępnionych przez interfejs API ich właściciel może wyłączyć udostępnianie linków lub cofnąć udostępnianie albumu w aplikacji Zdjęcia Google, co może uniemożliwić aplikacji dodawanie nowych użytkowników.

Aby udostępnić album:

1. Postępuj zgodnie z wytycznymi dotyczącymi UX i uzyskaj wyraźną zgodę użytkownika na utworzenie albumu udostępnionego.
2. Utwórz album i nagraj jego albumId. Jeśli masz już utworzony album, możesz pobrać jego albumId, tworząc listę albumów użytkownika.
3. Wywołaj albums.share, używając odpowiedniego elementu albumId wraz z opcjami udostępniania, które chcesz ustawić.
4. Zapisz wartość shareToken w odpowiedzi. Token udostępniania to identyfikator albumu udostępnionego, który może być używany na różnych kontach użytkowników.
5. Inny użytkownik może teraz uwierzytelnić się w Twojej aplikacji, a następnie join, opuścić lub pobrać szczegóły udostępnionego albumu za pomocą jego shareToken.

Opcje udostępniania

Poniższe opcje można ustawić podczas udostępniania albumu za pomocą parametru sharedAlbumOptions. Jeśli opcje nie są jawnie ustawione, używane są wartości domyślne.

Właściwość	Wartość domyślna	Opis
isCollaborative	false	Określa, czy inni użytkownicy Zdjęć Google mogą dodawać treści do albumu udostępnionego.
isCommentable	false	Określa, czy inni użytkownicy Zdjęć Google mogą komentować ten album udostępniony.

Przykładowe żądanie

Następująca prośba powoduje udostępnienie albumu przez wywołanie albums.share z opcjami. W odpowiedzi opisującej właściwości udostępniania albumu jest zwracana właściwość shareInfo.

REST

Oto nagłówek żądania POST służący do udostępniania albumu:

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

W treści żądania określ opcje udostępniania.

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

To żądanie zwraca następującą odpowiedź:

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

Właściwości albumu udostępnionego

W przypadku albumów utworzonych i udostępnionych przez Twoją aplikację wszystkie odpowiedzi zwracające wartość album zawierają dodatkową właściwość shareInfo. Ta właściwość jest zwracana podczas udostępniania, udostępniania lub retrieving albumów.

W tabeli poniżej znajdziesz listę właściwości shareInfo:

Właściwości
sharedAlbumOptions	Opcje określające, czy ktoś może dodawać elementy multimedialne do albumu udostępnionego lub dodawać do niego komentarze.
shareableUrl	Link do udostępnionego albumu ze Zdjęć Google. Każda osoba mająca link może wyświetlać zawartość albumu, dlatego należy zachować ostrożność. Pole shareableUrl jest zwracane tylko wtedy, gdy w albumie włączone jest udostępnianie linków. Jeśli użytkownik dołączył już do albumu, który nie jest udostępniany przez link, może użyć elementu productUrl tego albumu, aby uzyskać do niego dostęp. Dokument shareableUrl zostanie unieważniony, jeśli właściciel wyłączył udostępnianie linków w aplikacji Zdjęcia Google lub album został cofnięty.
shareToken	Token, który pozwala join, opuścić lub pobrać szczegóły albumu udostępnionego w imieniu użytkownika, który nie jest jego właścicielem. Dokument shareToken zostanie unieważniony, jeśli właściciel wyłączył udostępnianie linków w aplikacji Zdjęcia Google lub album został cofnięty.
isJoinable	True, jeśli użytkownicy mogą dołączać do albumu.
isJoined	True, jeśli użytkownik został dołączony do albumu. Dotyczy to zawsze właściciela albumu.
isOwned	True, jeśli album należy do użytkownika.

Uwaga: każda osoba, która ma identyfikator shareableUrl albumu, może wyświetlać jego zawartość.

Cofanie udostępniania albumu

Aby cofnąć udostępnianie albumu, który został wcześniej udostępniony przez aplikację, wywołaj metodę albums.unshare, używając identyfikatora albumId albumu.

Oprócz tego, że album przestanie być udostępniany, będą się też odbywać następujące rzeczy:

• Wszyscy inni użytkownicy utracą dostęp do albumu. Obejmuje to osoby, które miały udostępniony im album własnie za pomocą aplikacji Zdjęcia Google.
• Wszystkie treści dodane przez osoby niebędące właścicielami zostaną usunięte z albumu.
• Jeśli użytkownik dodał wcześniej zawartość albumu do swojej biblioteki, zostanie ona zachowana.
• Token udostępniania albumu i adres URL, który można udostępnić, zostaną unieważnione.

Przykładowe żądanie

REST

Oto nagłówek żądania POST, który pozwala cofnąć udostępnianie albumu:

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

Treść żądania musi być pusta.

Jeśli żądanie zostało wykonane, zwraca pustą odpowiedź z kodem stanu powodzenia HTTP. Jeśli żądanie nie zostało zrealizowane, zwraca kod stanu błędu HTTP z komunikatem o błędzie.

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
}

Pobieranie albumów udostępnionych i udostępnianie tokenów

Szczegóły albumu udostępnionego, w tym jego token udostępniania, są zwracane, gdy aplikacja udostępni album. Dane te możesz też pobrać później w jeden z poniższych sposobów.

Jeśli użytkownik, który jest obecnie połączony z Twoją aplikacją, jest jej właścicielem lub należy do albumu:

• W polu albums.get należy używać odpowiedniego elementu albumId.
• albums.list, jeśli album zawiera elementy multimedialne.
• Funkcja sharedAlbums.list zwraca wszystkie albumy udostępnione, do których użytkownik dołączył lub do którego należy. Aby pobrać tylko albumy utworzone przez aplikację, użyj parametru excludeNonAppCreatedData.
• W sharedAlbums.get za pomocą tokena udostępniania.

Jeśli użytkownik obecnie połączony z Twoją aplikacją nie jest członkiem albumu, możesz pobrać szczegóły albumu udostępnionego, używając usługi sharedAlbums.get przy użyciu prawidłowego tokena udostępniania.

Przykładowe żądanie

REST

Oto prośba o udostępnienie albumu przez shareToken:

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

Jeśli żądanie zostanie zrealizowane, zwrócone zostaną udostępnione szczegóły 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
}

Dołączanie do albumu udostępnionego

Twoja aplikacja może dołączyć do albumu udostępnionego w imieniu użytkownika przy użyciu tokena udostępniania albumu. Aby było to możliwe, muszą być spełnione następujące warunki:

• Aplikacja utworzyła i udostępniła album.
• Użytkownik, do którego chcesz dołączyć, nie jest jego właścicielem. Oznacza to, że pole isOwned w elemencie shareInfo albumu ma wartość false (fałsz).
• Token udostępniania jest prawidłowy.
• Pole isJoinable w shareInfo albumu ma wartość prawda.

Uwaga: gdy aplikacja udostępni album, jej właściciel może wyłączyć udostępnianie linków lub cofnąć udostępnianie albumu w aplikacji Zdjęcia Google. W takim przypadku token udostępniania albumu zostanie unieważniony, a pole isJoinable w polu isJoinable będzie puste, a aplikacja nie będzie mogła dołączać do albumu użytkowników.

REST

Oto nagłówek żądania POST umożliwiającego dołączenie do albumu udostępnionego:

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

W treści żądania podaj shareToken.

{
  "shareToken": "share-token"
}

Żądanie POST zwraca udostępniony element album, do którego dołączyła Twoja aplikacja w imieniu użytkownika.

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
}

Opuszczanie albumu udostępnionego

Aplikacja może opuścić album udostępniony w imieniu użytkownika przy użyciu tokena udostępniania tego albumu. Aby było to możliwe, muszą być spełnione następujące warunki:

• Twoja aplikacja utworzyła i udostępniła album.
• Użytkownik jest obecnie dołączony do albumu. Oznacza to, że pole isJoined w kolumnie shareInfo albumu ma wartość prawda.
• Użytkownik połączony z Twoją aplikacją nie jest właścicielem albumu. Oznacza to, że pole isOwned w kolumnie shareInfo albumu ma wartość false (fałsz).

REST

Oto nagłówek żądania POST zachęcającego do opuszczenia albumu udostępnionego:

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

W treści żądania podaj shareToken.

{
  "shareToken": "share-token"
}

Jeśli żądanie zostało wykonane, zwraca pustą odpowiedź z kodem stanu powodzenia HTTP. Jeśli żądanie nie zostało zrealizowane, zwraca kod stanu błędu HTTP z komunikatem o błędzie.

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
}

Właściwości udostępnianych elementów multimedialnych

Elementy multimedialne należące do albumów udostępnianych przez aplikację mają dodatkową właściwość: contributorInfo. Ta właściwość jest uwzględniana tylko podczas wyświetlania zawartości albumu udostępnionego.

Właściwość contributorInfo zawiera nazwę użytkownika, który dodał element multimedialny do albumu, oraz podstawowy adres URL zdjęcia profilowego.

Oto przykład:

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

Uwaga: właściwość contributorInfo jest zwracana tylko wtedy, gdy użytkownik przyzna dostęp do zakresu photoslibrary.sharing.