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:
- utworzyć album w imieniu użytkownika;
- Ustaw album jako udostępniony.
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:
- Postępuj zgodnie z wytycznymi dotyczącymi UX i uzyskaj wyraźną zgodę użytkownika na utworzenie albumu udostępnionego.
- Utwórz album
i nagraj jego
albumId
. Jeśli masz już utworzony album, możesz pobrać jegoalbumId
, tworząc listę albumów użytkownika. - Wywołaj
albums.share
, używając odpowiedniego elementualbumId
wraz z opcjami udostępniania, które chcesz ustawić. - 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. - 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 Dokument |
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 |
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. |
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 elementualbumId
. 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 parametruexcludeNonAppCreatedData
. - 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 elemencieshareInfo
albumu ma wartość false (fałsz). - Token udostępniania jest prawidłowy.
- Pole
isJoinable
wshareInfo
albumu ma wartość prawda.
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 kolumnieshareInfo
albumu ma wartość prawda. - Użytkownik połączony z Twoją aplikacją nie jest właścicielem albumu. Oznacza to, że pole
isOwned
w kolumnieshareInfo
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" } }