Von Ihrer App erstellte Alben können zwischen Nutzern geteilt werden und haben die Möglichkeit, diesen Nutzern zu erlauben, Kommentare zu hinterlassen oder ihre eigenen Medienelemente zum Album beizutragen.
Damit Sie ein Album über die Google Photos Library API teilen können, muss Ihre App folgende Voraussetzungen erfüllen:
Erforderlicher Authentifizierungsbereich
Damit Sie Inhalte teilen können, muss Ihre App den Autorisierungsbereich photoslibrary.sharing
anfordern.
Alben teilen
Bevor Sie ein Album teilen, beachten Sie Folgendes:
- Ihre App kann nur Alben teilen, die sie erstellt hat. Alben, die von anderen Apps wie Google Fotos erstellt wurden, können von Ihrer App nicht geteilt werden.
- Wenn Ihre App ein Album über die Library API teilt, wird eine URL zum Teilen generiert, über die jeder auf das Album zugreifen kann.
- Bei Alben, die über die API geteilt wurden, kann der Inhaber des Albums die Linkfreigabe deaktivieren oder die Freigabe des Albums in der Google Fotos App zurücknehmen. Dadurch wird möglicherweise verhindert, dass Ihre App neuen Nutzern hinzugefügt wird.
So teilen Sie ein Album:
- Folgen Sie den UX-Richtlinien und holen Sie die ausdrückliche Einwilligung des Nutzers ein, um ein geteiltes Album zu erstellen.
- Erstellen Sie das Album und nehmen Sie seine
albumId
auf. Wenn Sie das Album bereits erstellt haben, können Sie diealbumId
abrufen, indem Sie die Alben des Nutzers auflisten. - Rufen Sie
albums.share
mit der entsprechendenalbumId
und den Freigabeoptionen auf, die Sie festlegen möchten. - Notieren Sie den Wert
shareToken
in der Antwort. Das Freigabetoken ist eine Kennung für ein geteiltes Album, die für verschiedene Nutzerkonten verwendet werden kann. - Ein anderer Nutzer kann sich jetzt bei Ihrer App authentifizieren und dann mithilfe des
shareToken
-Objekts des geteilten Albums join, verlassen oder die Details abrufen.
Optionen zum Teilen
Die folgenden Optionen können beim Teilen eines Albums mit dem Parameter sharedAlbumOptions
festgelegt werden. Wenn die Optionen nicht explizit festgelegt sind, werden die Standardwerte verwendet.
Property | Standardwert | Beschreibung |
---|---|---|
isCollaborative |
false |
Legt fest, ob andere Google Fotos-Nutzer dem geteilten Album Inhalte hinzufügen dürfen. |
isCommentable |
false |
Legt fest, ob andere Google Fotos-Nutzer das geteilte Album kommentieren dürfen. |
Beispielanfrage
Mit der folgenden Anfrage wird ein Album geteilt, indem albums.share
mit Optionen aufgerufen wird. In der Antwort wird die Property shareInfo
zurückgegeben, mit der die Freigabeeigenschaften des Albums beschrieben werden.
REST
Hier ist eine POST-Anfrageheader zum Teilen eines Albums:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:share Content-type: application/json Authorization: Bearer oauth2-token
Legen Sie im Anfragetext die Freigabeoptionen fest.
{ "sharedAlbumOptions": { "isCollaborative": "true", "isCommentable": "true" } }
Diese Anfrage gibt die folgende Antwort zurück:
{ "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 }
Eigenschaften geteilter Alben
Bei Alben, die von Ihrer App erstellt und geteilt wurden, enthalten alle Antworten, die ein album
zurückgeben, die zusätzliche Eigenschaft shareInfo
. Diese Eigenschaft wird beim Teilen, Auflisten oder retrieving von Alben zurückgegeben.
In der folgenden Tabelle sind die shareInfo
-Attribute aufgeführt:
Attribute | |
---|---|
sharedAlbumOptions |
Optionen, die beschreiben, ob jemand Medienelemente zu einem geteilten Album hinzufügen oder es kommentieren darf. |
shareableUrl |
Ein Link zum geteilten Google Fotos-Album. Jeder, der über den Link verfügt, kann den Inhalt des Albums sehen, Sie sollten also vorsichtig vorgehen. Das Feld Eine |
shareToken |
Ein Token, mit dem ein geteiltes Album im Namen eines Nutzers, der nicht der Inhaber ist, join, verlassen oder die Details abgerufen werden kann. Eine |
isJoinable |
True , wenn Nutzer dem Album beitreten können. |
isJoined |
True , wenn der Nutzer dem Album beigetreten ist. Dies gilt immer für den Inhaber des Albums. |
isOwned |
True , wenn dem Nutzer das Album gehört. |
Freigabe eines Albums aufheben
Wenn du ein Album, das deine App zuvor geteilt hat, zurücknehmen möchtest, rufe über albumId
des Albums albums.unshare
auf.
Zusätzlich dazu, dass das Album nicht mehr geteilt wird, geschieht Folgendes:
- Alle Nichteigentümer verlieren den Zugriff auf das Album. Dazu gehören auch Personen, die das Album über die Google Fotos App speziell für sie freigegeben haben.
- Alle Inhalte, die von Nichteigentümern hinzugefügt wurden, werden aus dem Album entfernt.
- Wenn ein Nutzer die Inhalte des Albums bereits zu seiner Mediathek hinzugefügt hat, werden diese beibehalten.
- Das Teilen-Token und die URL zum Teilen des Albums werden ungültig.
Beispielanfrage
REST
Hier ist eine POST-Anfrageheader, um die Freigabe eines Albums aufzuheben:
POST https://photoslibrary.googleapis.com/v1/albums/album-id:unshare Content-type: application/json Authorization: Bearer oauth2-token
Der Anfragetext muss leer sein.
Wenn die Anfrage erfolgreich war, wird eine leere Antwort mit einem HTTP-Erfolgsstatuscode zurückgegeben. Wenn die Anfrage nicht erfolgreich war, wird ein HTTP-Fehlerstatuscode mit einer Fehlermeldung zurückgegeben.
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 }
Geteilte Alben abrufen und Tokens teilen
Die Details eines geteilten Albums, einschließlich des Teilen-Tokens, werden zurückgegeben, wenn Ihre App ein Album teilt. Sie können diese Details im Nachhinein auch so abrufen.
Wenn der aktuell mit Ihrer App verbundene Nutzer der Inhaber ist oder dem Album beigetreten ist:
- Mit
albums.get
unter Verwendung der entsprechendenalbumId
. - Mit
albums.list
, wenn das Album Medienelemente enthält. - Mit
sharedAlbums.list
, das alle geteilten Alben zurückgibt, denen der Nutzer beigetreten ist oder die er besitzt. Wenn Sie nur die von Ihrer App erstellten Alben abrufen möchten, verwenden Sie den ParameterexcludeNonAppCreatedData
. - Mit
sharedAlbums.get
unter Verwendung eines Freigabetokens.
Wenn der aktuell mit Ihrer App verbundene Nutzer nicht dem Album beigetreten ist, können Sie die Details eines geteilten Albums mit sharedAlbums.get
unter Verwendung eines gültigen Freigabetokens abrufen.
Beispielanfrage
REST
Hier ist eine Anfrage zum Abrufen eines Albums durch die shareToken
:
GET https://photoslibrary.googleapis.com/v1/sharedAlbums/share-token
Wenn die Anfrage erfolgreich ist, werden die freigegebenen Details von
album
zurückgegeben.
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 }
Einem geteilten Album beitreten
Ihre App kann mit dem Freigabetoken des Albums im Namen eines Nutzers einem geteilten Album beitreten. Dazu müssen die folgenden Bedingungen erfüllt sein:
- Ihre App hat das Album erstellt und geteilt.
- Der Nutzer, dem Sie dem Album beitreten möchten, ist nicht der Inhaber. Das heißt, das Feld
isOwned
in dershareInfo
des Albums ist auf „false“ gesetzt. - Das Freigabetoken ist gültig.
- Für das Feld
isJoinable
imshareInfo
des Albums ist „true“ festgelegt.
REST
Hier ist die POST-Anfrageheader für den Beitritt zu einem geteilten Album:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:join Content-type: application/json Authorization: Bearer oauth2-token
Geben Sie im Anfragetext den shareToken
an.
{ "shareToken": "share-token" }
Die POST-Anfrage gibt das freigegebene album
zurück, dem die App im Namen des Nutzers beigetreten ist.
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 }
Geteilte Alben verlassen
Ihre App kann geteilte Alben im Namen eines Nutzers verlassen, indem sie das Freigabetoken des Albums verwendet. Dazu müssen die folgenden Bedingungen erfüllt sein:
- Deine App hat das Album erstellt und geteilt.
- Der Nutzer ist derzeit dem Album beigetreten. Das heißt, das Feld
isJoined
imshareInfo
des Albums ist „true“. - Der mit Ihrer App verbundene Nutzer ist nicht der Inhaber des Albums. Das heißt, das Feld
isOwned
imshareInfo
des Albums ist auf „false“ gesetzt.
REST
Hier ist eine POST-Anfrageheader, um ein geteiltes Album zu verlassen:
POST https://photoslibrary.googleapis.com/v1/sharedAlbums:leave Content-type: application/json Authorization: Bearer oauth2-token
Geben Sie im Anfragetext den shareToken
an.
{ "shareToken": "share-token" }
Wenn die Anfrage erfolgreich war, wird eine leere Antwort mit einem HTTP-Erfolgsstatuscode zurückgegeben. Wenn die Anfrage nicht erfolgreich war, wird ein HTTP-Fehlerstatuscode mit einer Fehlermeldung zurückgegeben.
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 }
Eigenschaften der freigegebenen Medienelemente
Medienelemente, die zu Alben gehören, die von Ihrer App freigegeben wurden, haben die zusätzliche Property contributorInfo
.
Diese Eigenschaft ist nur beim Auflisten der Inhalte eines geteilten Albums enthalten.
Die Eigenschaft contributorInfo
enthält den Namen des Nutzers, der dem Album das Medienelement hinzugefügt hat, und eine Basis-URL zu seinem Profilbild.
Beispiel:
{ "id: "media-item-id", ..., "mediaMetadata": { ... } "contributorInfo": { "profilePictureBaseUrl": "profile-picture-base-url_use-only-with-parameters", "displayName": "name-of-user" } }