Álbuns criados pelo seu app podem ser compartilhados entre usuários, com opções para permitir que eles comentem ou contribuam com os próprios itens de mídia.
Para compartilhar um álbum pela API Google Photos Library, o app precisa fazer o seguinte:
- Criar um álbum em nome de um usuário.
- Defina o álbum como compartilhado.
Escopo de autenticação obrigatório
Para compartilhar conteúdo, seu app precisa solicitar o
escopo de autorização photoslibrary.sharing
.
Como compartilhar um álbum
Antes de compartilhar um álbum, considere o seguinte:
- O app só pode compartilhar álbuns criados por ele. Álbuns criados por outros apps, incluindo o Google Fotos, não podem ser compartilhados pelo seu app.
- Quando o app compartilha um álbum pela API Library, um URL compartilhável é gerado para que qualquer pessoa possa acessar o álbum.
- Nos álbuns compartilhados usando a API, o proprietário pode desativar o compartilhamento de link ou cancelar o compartilhamento do álbum no Google Fotos, o que pode impedir que o app adicione novos usuários.
Para compartilhar um álbum:
- Siga as diretrizes de UX e peça o consentimento explícito do usuário para criar um álbum compartilhado.
- Crie o álbum
e grave a
albumId
dele. Se você já criou o álbum, é possível recuperar oalbumId
dele listando os álbuns do usuário. - Chame
albums.share
usando oalbumId
relevante e as opções de compartilhamento que você quer definir. - Registre o valor
shareToken
na resposta. O token de compartilhamento é um identificador de um álbum compartilhado que pode ser usado em diferentes contas de usuário. - Agora, outro usuário pode se autenticar com seu app e depois
join,
sair ou
recuperar os detalhes
do álbum compartilhado usando o
shareToken
.
Opções de compartilhamento
As seguintes opções podem ser definidas ao compartilhar um álbum usando o parâmetro sharedAlbumOptions
. Se as opções não forem definidas explicitamente, os valores padrão serão usados.
Propriedade | Valor padrão | Descrição |
---|---|---|
isCollaborative |
false |
Define se outros usuários do Google Fotos podem adicionar conteúdo ao álbum compartilhado. |
isCommentable |
false |
Define se outros usuários do Google Fotos podem comentar no álbum compartilhado. |
Exemplo de solicitação
A solicitação a seguir compartilha um álbum chamando albums.share
com opções. Uma
propriedade shareInfo
é retornada na resposta que descreve as
propriedades de compartilhamento do álbum.
REST
Este é um cabeçalho de solicitação POST para compartilhar um álbum:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
No corpo da solicitação, especifique as opções de compartilhamento.
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
Essa solicitação retorna a seguinte resposta:
{ "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 }
Propriedades do álbum compartilhado
Para álbuns que foram criados e compartilhados pelo seu app, todas as respostas que
retornam um album
incluem uma propriedade extra,
shareInfo
. Essa
propriedade é retornada ao compartilhar,
listar ou
retrieving álbuns.
A tabela a seguir lista as propriedades shareInfo
:
Propriedades | |
---|---|
sharedAlbumOptions |
Opções que descrevem se alguém pode adicionar itens de mídia ou comentar em um álbum compartilhado. |
shareableUrl |
Um link para o álbum compartilhado do Google Fotos. Qualquer pessoa com o link pode ver o conteúdo do álbum, por isso ele precisa ser tratado com cuidado. O campo Uma |
shareToken |
Um token usado para join, sair ou recuperar os detalhes de um álbum compartilhado em nome de um usuário que não é o proprietário. Uma |
isJoinable |
True se os usuários puderem participar do álbum. |
isJoined |
True se o usuário estiver participando do álbum. Isso sempre acontece com o proprietário do álbum. |
isOwned |
True se o usuário for o proprietário do álbum. |
Cancelar o compartilhamento de um álbum
Para cancelar o compartilhamento de um álbum compartilhado anteriormente, chame
albums.unshare
usando o
albumId
do álbum.
Além do álbum não ser mais compartilhado, acontecerá o seguinte:
- Todos os não proprietários perderão o acesso ao álbum. Isso inclui as pessoas que compartilharam especificamente o álbum com elas pelo app Google Fotos.
- Todo o conteúdo adicionado por não proprietários será removido do álbum.
- Se um usuário já tiver adicionado o conteúdo do álbum à biblioteca, esse conteúdo será mantido.
- O token e o URL compartilhável do álbum serão invalidados.
Exemplo de solicitação
REST
Este é um cabeçalho de solicitação POST para cancelar o compartilhamento de um álbum:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
O corpo da solicitação precisa estar vazio.
Se a solicitação for bem-sucedida, ela retornará uma resposta vazia com um código de status de sucesso HTTP. Se a solicitação não for bem-sucedida, ela retornará um código de status de erro HTTP com uma mensagem de erro.
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 }
Como recuperar álbuns compartilhados e compartilhar tokens
Os detalhes de um álbum compartilhado, incluindo o token de compartilhamento, são retornados quando o app compartilha um álbum. Também é possível recuperar esses detalhes posteriormente das maneiras a seguir.
Se o usuário conectado ao seu app for o proprietário ou fizer parte do álbum:
- Com
albums.get
usando oalbumId
relevante. - Com
albums.list
, se houver itens de mídia no álbum. - Com
sharedAlbums.list
, que retorna todos os álbuns compartilhados de que o usuário está participando ou é proprietário. Para recuperar somente os álbuns criados pelo seu app, use o parâmetroexcludeNonAppCreatedData
. - Com
sharedAlbums.get
usando um token de compartilhamento.
Se o usuário conectado ao seu app não estiver associado ao álbum, você poderá
recuperar os detalhes de um álbum compartilhado com
sharedAlbums.get
usando um
token de compartilhamento válido.
Exemplo de solicitação
REST
Esta é uma solicitação para obter um álbum pela shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Se a solicitação for bem-sucedida, ela retornará os detalhes de
album
compartilhados.
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 }
Participar de um álbum compartilhado
Seu app pode participar de um álbum compartilhado em nome de um usuário com o token de compartilhamento do álbum. Para isso, as seguintes condições precisam ser atendidas:
- Seu app criou e compartilhou o álbum.
- O usuário que você quer associar ao álbum não é o proprietário dele. Ou seja, o
campo
isOwned
noshareInfo
do álbum é falso. - O token de compartilhamento é válido.
- O campo
isJoinable
no arquivoshareInfo
do álbum é verdadeiro.
REST
Este é um cabeçalho de solicitação POST para participar de um álbum compartilhado:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
No corpo da solicitação, especifique o shareToken
.
{ "shareToken": "share-token" }
A solicitação POST retorna as album
compartilhadas em que seu app entrou em nome do usuário.
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 }
Saindo de um álbum compartilhado
Seu app pode sair de um álbum compartilhado em nome de um usuário usando o token de compartilhamento do álbum. Para isso, as seguintes condições precisam ser atendidas:
- O app criou e compartilhou o álbum.
- O usuário está participando do álbum. Ou seja, o campo
isJoined
noshareInfo
do álbum é verdadeiro. - O usuário conectado ao seu app não é o proprietário do álbum. Ou seja, o
campo
isOwned
noshareInfo
do álbum é falso.
REST
Este é um cabeçalho de solicitação POST para sair de um álbum compartilhado:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
No corpo da solicitação, especifique o shareToken
.
{ "shareToken": "share-token" }
Se a solicitação for bem-sucedida, ela retornará uma resposta vazia com um código de status de sucesso HTTP. Se a solicitação não for bem-sucedida, ela retornará um código de status de erro HTTP com uma mensagem de erro.
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 }
Propriedades do item de mídia compartilhada
Os itens de mídia que pertencem aos
álbuns compartilhados pelo seu app contêm uma propriedade adicional,
contributorInfo
.
Essa propriedade só é incluída ao listar o
conteúdo de um álbum compartilhado.
A propriedade contributorInfo
inclui o nome do usuário que adicionou o item
de mídia ao álbum e um
URL base da imagem de
perfil.
Veja um exemplo:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }