הוספת הטבות

העשרה מאפשרת לאפליקציה לשלוט במבנה ובהצגה של תמונות באלבום ב-Google Photos. הם מאפשרים להציג את המשתמש עם הקשר נוסף באמצעות הערות טקסט או הערות מיקום וסידור/קבוצה תמונות שמספרות סיפור ביחד.

היקף ההרשאה הנדרש

כדי להוסיף העשרות, נדרש לפחות אחד מההיקפים הבאים:

• photoslibrary.appendonly
• photoslibrary.library
• photoslibrary.sharing

בכל היקף הרשאות, הקריאה enrichAlbum מוגבלת רק לאלבומים שנוצרו על ידי האפליקציה.

כשמשתמשים בהיקף .sharing, המדיניות enrichAlbum מוגבלת לנסיבות שבו המפתח פועל בשם הבעלים של האלבום המשותף.

סוגי העשרה

אפליקציית Google Photos תומכת בשלושה סוגים של העשרות באלבומים: טקסט, מיקומים ומפות.

העשרת טקסט

העשרת טקסט היא מחרוזת טקסט פשוטה שאפשר להוסיף כדי להוסיף הערות אלבום.

העשרת מיקום

העשרת מיקום היא סמן והשם של המקום שניתן להוסיף כדי להוסיף הערות למיקום.

העשרות מפה

העשרת מפה היא מפה עם מוצא ויעד ספציפיים שיכולים להיות נוסף לאלבום.

מיקומים

כדי להוסיף פריטי מדיה והעשרת אלבום, צריך לציין את המיקום של האלבום. מיקום הוא אופציונלי לפריטי מדיה, אבל חובה לציין מיקום לאלבום העשרה.

ניתן לציין מיקום רק כאשר יצירת פריט מדיה או העשרה. לא ניתן לארגן מחדש פריטי מדיה קיימים באלבום, לכן חשוב להגדיר את המיקום של הפריט כשמוסיפים אותו.

תחילת האלבום

ניתן להוסיף פריט מדיה/העשרה בתחילת האלבום כפריט המוחלט את המיקום שלו.

סוף האלבום

ניתן להוסיף פריט מדיה/העשרה בסוף האלבום כפריט המוחלט את המיקום שלו.

ביחס לפריט המדיה

ניתן להוסיף פריט מדיה/העשרה ביחס לפריט מדיה שמתחיל אחרי מהו המיקום שלו באלבום.

ביחס לפריט העשרה

ניתן להוסיף פריט מדיה/העשרה ביחס לפריט העשרה אחרי המיקום שלו באלבום.

הוספת העשרה לאלבום

ההעשרה מתווספת אחת בכל פעם, ויש להוסיף אותה למיקום מסוים באלבום. כדי להוסיף העשרות לאלבום, התקשר albums.addEnrichment

אם הבקשה מצליחה, היא מחזירה את הערך id של פריט העשרה, יכול לשמש למיקום פריטי מדיה או העשרות אחרות.

REST

הנה בקשת POST:

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

גוף הבקשה מורכב מפריט ההעשרה ומהמיקום שלו:

{
  "newEnrichmentItem": {
    enrichment-to-be-added
  },
  "albumPosition": {
    position-of-enrichment
}

הנה תגובה לדוגמה:

{
  "enrichmentItem": {
    "id": "enrichment-item-id",
  }
}

Java

try {
  // Create the enrichment using the NewEnrichmentItemFactory helper
  NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createTextEnrichment("");

  // Set the position of the enrichment within the album
  AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

  // To add an enrichment, specify the album, the enrichment item,
  // and the position in the album where the enrichment is to be added
  AddEnrichmentToAlbumResponse response = photosLibraryClient
      .addEnrichmentToAlbum(albumId, newEnrichmentItem, albumPosition);
  // The response contains an EnrichmentItem
  // whose ID can be used to position media items or other enrichments
  EnrichmentItem enrichmentItem = response.getEnrichmentItem();
  String itemId = enrichmentItem.getId();
} catch (ApiException e) {
  // Handle error
}

PHP

// Create the enrichment item using the PhotosLibraryResourceFactory helper
$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("");
// ...
// Set the position of the enrichment within the album
$position = new AlbumPosition();
// ...
try {
    // To add an enrichment, specify the album, the enrichment item,
    // and the position in the album where the enrichment is to be added
    $response = $photosLibraryClient->addEnrichmentToAlbum($albumId, $newEnrichmentItem, $position);
    // The response contains an EnrichmentItem
    // whose ID can be used to position media items or other enrichments
    $enrichmentItem = $response->getEnrichmentItem();
    $itemId = $enrichmentItem->getId();

} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

העשרות נתמכות

העשרת טקסט

העשרת טקסט מכילה מחרוזת טקסט יחידה (לא יותר מ-1000 תווים), כמו שמוצגת בדוגמה הבאה:

REST

{
  "text": "Text to be shown"
}

Java

// Use the NewEnrichmentItemFactory helper to create a text enrichment item
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createTextEnrichment("text to be shown");

PHP

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithText("text to be shown");

העשרת מיקום

העשרת מיקומים כוללות שם מיקום שרירותי וקו רוחב המיקום של קו האורך. האורך המקסימלי של הטקסט locationName הוא 500 תווים.

REST

{
  "location": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a location enrichment
// with the name, latitude, and longitude of the location
NewEnrichmentItem newEnrichmentItem =
    NewEnrichmentItemFactory.createLocationEnrichment("Australia", -21.197, 95.821);

PHP

// Create a new location object and set the name, latitude, and longitude of the location
$newLocation = new Location();
$newLocation->setLocationName("Australia");
$newLocation->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$newEnrichmentItem = PhotosLibraryResourceFactory::newEnrichmentItemWithLocation($newLocation);

העשרות מפה

המונח 'העשרה במפה' מציג שני מיקומים, שכל אחד מהם כולל שם וקו רוחב וקו אורך. בדומה להעשרת המיקום, locationName בתוך source ו-destination מוגבלים ל-500 תווים.

REST

{
  "origin": {
    "locationName": "Australia",
    "latlng": {
      "latitude": "-21.197",
      "longitude": "95.821"
    }
  },
  "destination": {
    "locationName": "San Francisco",
    "latlng": {
      "latitude": "37.757",
      "longitude": "122.507"
    }
  }
}

Java

// Use the NewEnrichmentItemFactory helper to create a map enrichment item for
// an origin and a destination location
NewEnrichmentItem newEnrichmentItem = NewEnrichmentItemFactory.createMapEnrichment(
    "Australia", -21.197, 95.821, // origin
    "San Francisco", 37.757, 122.507 // destination
);

PHP

// Create two new location objects to create a map enrichment item
// for an origin and a destination location
$locationAustralia = new Location();
$locationAustralia->setLocationName("Australia");
$locationAustralia->setLatlng((new LatLng())->setLatitude(-21.197)->setLongitude(95.821));

$locationSanFrancisco = new Location();
$locationSanFrancisco->setLocationName("San Francisco");
$locationSanFrancisco->setLatlng((new LatLng())->setLatitude(37.757)->setLongitude(122.507));

$newEnrichmentItem =
  PhotosLibraryResourceFactory::newEnrichmentItemWithMap($locationAustralia, $locationSanFrancisco);

מיקום נתמך

תחילת האלבום

המיקום FIRST_IN_ALBUM מתייחס להתחלת האלבום. פריטים שנמצאו כאן מוצגים למשתמש קודם:

REST

{
  "position": "FIRST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createFirstInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::FIRST_IN_ALBUM);

סוף האלבום

המיקום LAST_IN_ALBUM מתייחס לסוף האלבום. פריטים שנמצאים כאן מוצגות למשתמש האחרון.

REST

{
  "position": "LAST_IN_ALBUM",
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createLastInAlbum();

PHP

$albumPosition = new AlbumPosition();
$albumPosition->setPosition(PositionType::LAST_IN_ALBUM);

ביחס לפריט המדיה

ציון המיקום relativeMediaItem מתייחס למיקום ביחס קובץ מדיה. הפריטים יתווספו אחרי פריט המדיה שצוין.

REST

{
  "position": "after-media-item",
  "relativeMediaItemId": "media-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterMediaItem(mediaItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);

ביחס לפריט העשרה

ציון relativeEnrichmentItemId מתייחס למיקום ביחס פריט העשרה. הפריטים יתווספו אחרי פריט העשרה שצוין.

REST

{
  "position": "after-enrichment-item",
  "relativeEnrichmentItemId": "enrichment-item-id"
}

Java

AlbumPosition albumPosition = AlbumPositionFactory.createAfterEnrichmentItem(enrichmentItemId);

PHP

$albumPosition = PhotosLibraryResourceFactory::albumPositionAfterEnrichmentItem($enrichmentItemId);

שינוי העשרה

בשלב זה, אין דרך לשנות העשרה. אבל ברגע שהעשירה נוצר ונוסף לאלבום, המשתמש יכול לשנות את ההעשרות באמצעות אפליקציית Google Photos.