Medien teilen

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:

1. Alben im Namen eines Nutzers erstellen
2. Legen Sie fest, dass dieses Album geteilt wird.

Hinweis :Bevor Sie ein Album teilen, holen Sie die ausdrückliche Einwilligung des Nutzers ein und beachten Sie die UX-Richtlinien.

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:

1. Folgen Sie den UX-Richtlinien und holen Sie die ausdrückliche Einwilligung des Nutzers ein, um ein geteiltes Album zu erstellen.
2. Erstellen Sie das Album und nehmen Sie seine albumId auf. Wenn Sie das Album bereits erstellt haben, können Sie die albumId abrufen, indem Sie die Alben des Nutzers auflisten.
3. Rufen Sie albums.share mit der entsprechenden albumId und den Freigabeoptionen auf, die Sie festlegen möchten.
4. 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.
5. 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 shareableUrl wird nur zurückgegeben, wenn für das Album die Linkfreigabe aktiviert ist. Wenn ein Nutzer bereits einem Album ohne Linkfreigabe beigetreten ist, kann er stattdessen über die productUrl des Albums darauf zugreifen. Eine shareableUrl wird ungültig, wenn der Inhaber die Linkfreigabe in der Google Fotos App deaktiviert oder wenn die Freigabe des Albums aufgehoben wird.
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 shareToken wird ungültig, wenn der Inhaber die Linkfreigabe in der Google Fotos App deaktiviert oder wenn die Freigabe des Albums aufgehoben wird.
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.

Achtung :Jeder mit der shareableUrl eines Albums kann sich dessen Inhalt ansehen.

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 entsprechenden albumId.
• 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 Parameter excludeNonAppCreatedData.
• 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 der shareInfo des Albums ist auf „false“ gesetzt.
• Das Freigabetoken ist gültig.
• Für das Feld isJoinable im shareInfo des Albums ist „true“ festgelegt.

Achtung :Nachdem Ihre App ein Album geteilt hat, kann der Inhaber die Linkfreigabe in der Google Fotos App deaktivieren oder die Freigabe des Albums aufheben. In diesem Fall wird das Freigabetoken des Albums ungültig, das Feld isJoinable ist auf „false“ gesetzt und Ihre App kann dem Album nicht mehr beitreten.

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 im shareInfo des Albums ist „true“.
• Der mit Ihrer App verbundene Nutzer ist nicht der Inhaber des Albums. Das heißt, das Feld isOwned im shareInfo 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"
  }
}

Hinweis: Das Attribut contributorInfo wird nur zurückgegeben, wenn der Nutzer Zugriff auf den Bereich photoslibrary.sharing gewährt hat.