อัปโหลดสื่อ

การอัปโหลดรายการสื่อมี 2 ขั้นตอนดังนี้

  1. อัปโหลดไบต์ของไฟล์สื่อไปยังเซิร์ฟเวอร์ของ Google โดยใช้ปลายทางการอัปโหลด ซึ่งจะแสดงผลโทเค็นการอัปโหลดซึ่งระบุไบต์ที่อัปโหลด
  2. ใช้การเรียกใช้แบบกลุ่มกับโทเค็นการอัปโหลดเพื่อ สร้างรายการสื่อในบัญชี Google Photos ของผู้ใช้

ขั้นตอนเหล่านี้จะสรุปกระบวนการอัปโหลดรายการสื่อรายการเดียว หากคุณ อัปโหลดรายการสื่อหลายรายการ (สำหรับแอปพลิเคชันเวอร์ชันที่ใช้งานจริง) ให้อ่านแนวทางปฏิบัติแนะนำสำหรับการอัปโหลดเพื่อปรับปรุง ที่มีประสิทธิภาพในการอัปโหลด

ก่อนเริ่มต้น

ขอบเขตการให้สิทธิ์ที่จำเป็น

การอัปโหลดรายการสื่อไปยังไลบรารีหรืออัลบั้มของผู้ใช้จะต้องมีสิ่งต่อไปนี้ ขอบเขต photoslibrary.appendonly หรือ photoslibrary

นอกจากนี้ยังสร้างรายการสื่อโดยใช้ขอบเขต photoslibrary.sharing ได้ด้วย ถึง สร้างรายการที่มีขอบเขต photoslibrary.sharing คุณต้องสร้าง อัลบั้ม และทำเครื่องหมายเป็นแชร์โดยใช้ shareAlbum จากนั้นคุณจะสร้างรายการสื่อได้ ที่แชร์กับผู้ใช้ในอัลบั้ม คุณไม่สามารถสร้างรายการใน คลังภาพของผู้ใช้หรือในอัลบั้มที่แอปของคุณยังไม่ได้แชร์

เมื่อแสดงรายการอัลบั้ม พร็อพเพอร์ตี้ isWriteable จะระบุว่า สามารถเข้าถึงเพื่อสร้างสื่อในอัลบั้มหนึ่งๆ ได้

ประเภทและขนาดของไฟล์ที่ยอมรับ

คุณสามารถอัปโหลดไฟล์ประเภทที่ระบุไว้ในตารางด้านล่าง

ประเภทสื่อ ประเภทไฟล์ที่ยอมรับ ขนาดไฟล์สูงสุด
Photos AVIF, BMP, GIF, HEIC, ICO, JPG, PNG, TIFF, WEBP, ไฟล์ RAW บางประเภท 200 MB
วิดีโอ 3GP, 3G2, ASF, AVI, DIVX, M2T, M2TS, M4V, MKV, MMV, MOD, MOV, MP4 MPG, MTS, TOD, WMV 20 GB

ขั้นตอนที่ 1: การอัปโหลดไบต์

อัปโหลดไบต์ไปยัง Google โดยใช้คำขออัปโหลด คำขออัปโหลดที่ประสบความสำเร็จ จะแสดงผลโทเค็นการอัปโหลดในรูปแบบของสตริงข้อความดิบ ใช้การอัปโหลดเหล่านี้ โทเค็นเพื่อสร้างรายการสื่อที่มีการเรียก batchCreate

REST

ใส่ช่องต่อไปนี้ในส่วนหัวของคำขอ POST

ช่องส่วนหัว
Content-type ตั้งค่าเป็น application/octet-stream
X-Goog-Upload-Content-Type แนะนำ ตั้งค่าเป็นประเภท MIME ของไบต์ที่คุณกำลังอัปโหลด ประเภท MIME ทั่วไป ได้แก่ image/jpeg image/png และ image/gif
X-Goog-Upload-Protocol ตั้งค่าเป็น raw

ต่อไปนี้คือส่วนหัวของคำขอ POST

POST https://photoslibrary.googleapis.com/v1/uploads
Authorization: Bearer oauth2-token
Content-type: application/octet-stream
X-Goog-Upload-Content-Type: mime-type
X-Goog-Upload-Protocol: raw

ในเนื้อหาคำขอ ให้ใส่ไบนารีของไฟล์ดังนี้ 

media-binary-data

หากคำขอ POST นี้สำเร็จ โทเค็นการอัปโหลดจะอยู่ในรูปแบบ ของสตริงข้อความดิบ จะแสดงผลเป็นเนื้อหาการตอบกลับ เพื่อสร้างสื่อ โปรดใช้สตริงข้อความเหล่านี้ในการเรียกใช้ batchCreate

upload-token

Java

// Open the file and automatically close it after upload
try (RandomAccessFile file = new RandomAccessFile(pathToFile, "r")) {
  // Create a new upload request
  UploadMediaItemRequest uploadRequest =
      UploadMediaItemRequest.newBuilder()
              // The media type (e.g. "image/png")
              .setMimeType(mimeType)
              // The file to upload
              .setDataFile(file)
          .build();
  // Upload and capture the response
  UploadMediaItemResponse uploadResponse = photosLibraryClient.uploadMediaItem(uploadRequest);
  if (uploadResponse.getError().isPresent()) {
    // If the upload results in an error, handle it
    Error error = uploadResponse.getError().get();
  } else {
    // If the upload is successful, get the uploadToken
    String uploadToken = uploadResponse.getUploadToken().get();
    // Use this upload token to create a media item
  }
} catch (ApiException e) {
  // Handle error
} catch (IOException e) {
  // Error accessing the local file
}

PHP

try {
    // Create a new upload request by opening the file
    // and specifying the media type (e.g. "image/png")
    $uploadToken = $photosLibraryClient->upload(file_get_contents($localFilePath), null, $mimeType);
} catch (\GuzzleHttp\Exception\GuzzleException $e) {
    // Handle error
}

ขนาดไฟล์ที่แนะนำสำหรับรูปภาพคือน้อยกว่า 50 MB ไฟล์ที่มีขนาดใหญ่กว่า 50 MB มีแนวโน้มว่าจะมีปัญหาด้านประสิทธิภาพ

API คลังภาพของ Google Photos รองรับ การอัปโหลดที่ดำเนินการต่อได้ กลับมาใช้งานต่อได้ การอัปโหลดช่วยให้คุณแบ่งไฟล์สื่อออกเป็นหลายๆ ส่วนและอัปโหลด ในแต่ละครั้ง

ขั้นตอนที่ 2: การสร้างรายการสื่อ

หลังจากอัปโหลดไบต์ของไฟล์สื่อแล้ว คุณจะสร้างไฟล์เหล่านั้นเป็นสื่อได้ รายการใน Google Photos โดยใช้โทเค็นการอัปโหลด โทเค็นการอัปโหลดถูกต้อง เป็นเวลา 1 วันหลังจากที่สร้าง จะมีการเพิ่มรายการสื่อลงในรายการสื่อ ไลบรารี รายการสื่อสามารถเป็นได้เฉพาะ ที่เพิ่มลงในอัลบั้มแล้ว ที่แอปของคุณสร้างขึ้น โปรดดูข้อมูลเพิ่มเติมที่ขอบเขตการให้สิทธิ์

หากต้องการสร้างรายการสื่อใหม่ ให้เรียกใช้ mediaItems.batchCreate โดยระบุรายการ newMediaItems newMediaItem แต่ละรายการมีการอัปโหลด โทเค็นที่ระบุภายใน simpleMediaItem และคำอธิบายที่ไม่บังคับ ที่จะแสดงต่อผู้ใช้

ฟิลด์คำอธิบายมีอักขระได้ไม่เกิน 1,000 ตัวและควรประกอบด้วย ข้อความที่มีความหมายที่ผู้ใช้สร้างขึ้นได้ ตัวอย่างเช่น "การเดินทางไปยังสวนสาธารณะ" หรือ "อาหารค่ำวันหยุด" อย่ารวมข้อมูลเมตา เช่น ชื่อไฟล์ หรือข้อความอื่นๆ ที่สร้างขึ้นโดยอัตโนมัติ

เพื่อประสิทธิภาพที่ดีที่สุด ให้ลดจำนวนการโทรไปยัง mediaItems.batchCreate โดยรวมรายการสื่อหลายๆ รายการไว้ในการเรียกครั้งเดียว รอเสมอ จนกว่าคำขอก่อนหน้าจะเสร็จสมบูรณ์ ก่อนที่จะเรียกใช้ฟังก์ชัน ผู้ใช้คนเดียวกัน

คุณสามารถสร้างรายการสื่อรายการเดียวหรือหลายรายการในคลังของผู้ใช้ได้ โดยระบุคำอธิบายและโทเค็นการอัปโหลดที่เกี่ยวข้อง

REST

ต่อไปนี้คือส่วนหัวของคำขอ POST

POST https://photoslibrary.googleapis.com/v1/mediaItems:batchCreate
Content-type: application/json
Authorization: Bearer oauth2-token

เนื้อหาของคำขอควรระบุรายการ newMediaItems

{
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

Java

try {
  // Create a NewMediaItem with the following components:
  // - uploadToken obtained from the previous upload request
  // - filename that will be shown to the user in Google Photos
  // - description that will be shown to the user in Google Photos
  NewMediaItem newMediaItem = NewMediaItemFactory
          .createNewMediaItem(uploadToken, fileName, itemDescription);
  List<NewMediaItem> newItems = Arrays.asList(newMediaItem);

  BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);
  for (NewMediaItemResult itemsResponse : response.getNewMediaItemResultsList()) {
    Status status = itemsResponse.getStatus();
    if (status.getCode() == Code.OK_VALUE) {
      // The item is successfully created in the user's library
      MediaItem createdItem = itemsResponse.getMediaItem();
    } else {
      // The item could not be created. Check the status and try again
    }
  }
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $newMediaItems = [];
    // Create a NewMediaItem with the following components:
    // - uploadToken obtained from the previous upload request
    // - filename that will be shown to the user in Google Photos
    // - description that will be shown to the user in Google Photos
    $newMediaItems[0] = PhotosLibraryResourceFactory::newMediaItemWithDescriptionAndFileName(
            $uploadToken, $itemDescription, $fileName);

    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems);
    foreach ($response->getNewMediaItemResults() as $itemResult) {
        $status = $itemResult->getStatus();
        if ($status->getCode() != Code::OK) {
            // Error while creating the item.
        }
    }
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

คุณสามารถเพิ่มรายการสื่อลงในไลบรารีและในอัลบั้มได้โดยระบุ อัลบั้ม id สำหรับข้อมูลเพิ่มเติม โปรดดู สร้างอัลบั้ม

แต่ละอัลบั้มมีรายการสื่อได้สูงสุด 20,000 รายการ คำขอสร้างสื่อ รายการในอัลบั้มที่จะเกินขีดจำกัดนี้จะไม่สามารถใช้งานได้

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
   , ...
  ]
}

Java

try {
  // Create new media items in a specific album
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems, ['albumId' => $albumId]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

คุณยังระบุ albumId และ albumPosition ให้ แทรกรายการสื่อในตำแหน่งที่เจาะจงในอัลบั้ม

REST

{
  "albumId": "album-id",
  "newMediaItems": [
    {
      "description": "item-description",
      "simpleMediaItem": {
        "fileName": "filename",
        "uploadToken": "upload-token"
      }
    }
    , ...
  ],
  "albumPosition": {
    "position": "after-media-item",
    "relativeMediaItemId": "media-item-id"
  }
}

Java

try {
  // Create new media items in a specific album, positioned after a media item
  AlbumPosition positionInAlbum = AlbumPositionFactory.createFirstInAlbum();
  BatchCreateMediaItemsResponse response = photosLibraryClient
      .batchCreateMediaItems(albumId, newItems, positionInAlbum);
  // Check the response
} catch (ApiException e) {
  // Handle error
}

PHP

try {
    $albumPosition = PhotosLibraryResourceFactory::albumPositionAfterMediaItem($mediaItemId);
    $response = $photosLibraryClient->batchCreateMediaItems($newMediaItems,
        ['albumId' => $albumId, 'albumPosition' => $albumPosition]);
} catch (\Google\ApiCore\ApiException $e) {
    // Handle error
}

สำหรับรายละเอียดเพิ่มเติมเกี่ยวกับการวางตำแหน่งในอัลบั้ม โปรดดูที่ เพิ่มคุณค่า

คำตอบในการสร้างรายการ

การเรียก mediaItems.batchCreate จะแสดงผลลัพธ์สำหรับรายการสื่อแต่ละรายการ ที่คุณพยายามสร้าง รายการของ newMediaItemResults จะระบุสถานะและ มี uploadToken สำหรับคำขอ รหัสสถานะที่ไม่ใช่ 0 ระบุถึง

REST

หากสร้างรายการสื่อทั้งหมดสำเร็จแล้ว คำขอจะแสดงผล สถานะ HTTP: 200 OK หากสร้างรายการสื่อบางรายการไม่ได้ คำขอจะแสดงสถานะ HTTP 207 MULTI-STATUS เพื่อระบุ สำเร็จบางส่วน

{
  "newMediaItemResults": [
    {
      "uploadToken": "upload-token",
      "status": {
        "message": "Success"
      },
      "mediaItem": {
        "id": "media-item-id",
        "description": "item-description",
        "productUrl": "https://photos.google.com/photo/photo-path",
        "mimeType": "mime-type",
        "mediaMetadata": {
          "width": "media-width-in-px",
          "height": "media-height-in-px",
          "creationTime": "creation-time",
          "photo": {}
        },
        "filename": "filename"
      }
    },
    {
      "uploadToken": "upload-token",
      "status": {
        "code": 13,
        "message": "Internal error"
      }
    }
  ]
}

Java

BatchCreateMediaItemsResponse response = photosLibraryClient.batchCreateMediaItems(newItems);

// The response contains a list of NewMediaItemResults
for (NewMediaItemResult result : response.getNewMediaItemResultsList()) {
  // Each result item is identified by its uploadToken
  String uploadToken = result.getUploadToken();
  Status status = result.getStatus();

  if (status.getCode() == Code.OK_VALUE) {
    // If the request is successful, a MediaItem is returned
    MediaItem mediaItem = result.getMediaItem();
    String id = mediaItem.getId();
    String productUrl = mediaItem.getProductUrl();
    // ...
  }
}

PHP

// The response from a call to batchCreateMediaItems returns a list of NewMediaItemResults
foreach ($response->getNewMediaItemResults() as $itemResult) {
    // Each result item is identified by its uploadToken
    $itemUploadToken = $itemResult->getUploadToken();
    // Verify the status of each entry to ensure that the item has been uploaded correctly
    $itemStatus = $itemResult->getStatus();
    if ($itemStatus->getCode() != Code::OK) {
        // Error when item is being created
    } else {
        // Media item is successfully created
        // Get the MediaItem object from the response
        $mediaItem = $itemResult->getMediaItem();
        // It contains details such as the Id of the item, productUrl
        $id = $mediaItem->getId();
        $productUrl = $mediaItem->getProductUrl();
        // ...
    }
}

หากเพิ่มรายการสำเร็จแล้ว ระบบจะแสดงผล mediaItem ที่มี mediaItemId, productUrl และ mediaMetadata สำหรับข้อมูลเพิ่มเติม โปรดดู เข้าถึงรายการสื่อ

หากรายการสื่อเป็นวิดีโอ คุณต้องประมวลผลรายการนั้นก่อน mediaItem มี status ภายใน mediaMetadata ที่อธิบายการประมวลผล สถานะของไฟล์วิดีโอ ไฟล์ที่อัปโหลดใหม่จะแสดงสถานะ PROCESSING ก่อนที่จะREADY โปรดดูรายละเอียดที่หัวข้อ เข้าถึงรายการสื่อ

หากคุณพบข้อผิดพลาดระหว่างการโทรนี้ โปรดทำตาม แนวทางปฏิบัติแนะนำ แล้วลองส่งคำขออีกครั้ง คุณอาจต้องติดตามรายการที่เพิ่มสำเร็จเพื่อให้แทรกรูปภาพได้ ลงในอัลบั้มในตำแหน่งที่ถูกต้องในคำขอถัดไป สำหรับข้อมูลเพิ่มเติม ดูข้อมูลได้ที่ สร้างอัลบั้ม

ผลลัพธ์จะส่งคืนในลำดับเดียวกับโทเค็นการอัปโหลดเสมอ ส่งแล้ว

แนวทางปฏิบัติแนะนำสำหรับการอัปโหลด

แนวทางปฏิบัติแนะนำและแหล่งข้อมูลต่อไปนี้จะช่วยปรับปรุงประสิทธิภาพโดยรวม ที่มีการอัปโหลด:

  • ใช้ไลบรารีของไคลเอ็นต์ที่รองรับ
  • ทำตามแนวทางปฏิบัติแนะนำสำหรับการลองใหม่และจัดการกับข้อผิดพลาด โปรดคำนึงถึงประเด็นต่อไปนี้เสมอ
    • ข้อผิดพลาด 429 รายการอาจเกิดขึ้นเมื่อโควต้าของคุณหมด หรือคุณถูกจำกัดอัตราการโทรเนื่องจากโทรเร็วเกินไป ตรวจสอบว่า คุณไม่ได้โทรหา batchCreate สำหรับผู้ใช้รายเดียวกัน จนกว่า คำขอเสร็จสมบูรณ์แล้ว
    • ข้อผิดพลาด 429 รายการต้องมีการหน่วงเวลาอย่างน้อย 30s ก่อนที่จะลองอีกครั้ง ใช้ Exponential Backoff เมื่อส่งคำขออีกครั้ง
    • เกิดข้อผิดพลาด 500 รายการเมื่อเซิร์ฟเวอร์พบข้อผิดพลาด เมื่ออัปโหลด กรณีนี้น่าจะเป็นเพราะการเรียกเขียนหลายครั้ง (เช่น batchCreate) ให้กับผู้ใช้รายเดียวกันได้ในเวลาเดียวกัน ตรวจสอบรายละเอียดของ คำขอของคุณและอย่าโทรหา batchCreate พร้อมกัน
  • ใช้ขั้นตอนการอัปโหลดที่ดำเนินการต่อได้เพื่อ ทำให้การอัปโหลดของคุณมีประสิทธิภาพมากขึ้นในกรณีที่เครือข่ายหยุดชะงัก การใช้แบนด์วิดท์โดยให้คุณดำเนินการต่อสำหรับการอัปโหลดที่ไม่สมบูรณ์ ซึ่งมีความสำคัญเมื่ออัปโหลดจากอุปกรณ์เคลื่อนที่ของไคลเอ็นต์ หรือ เมื่ออัปโหลดไฟล์ขนาดใหญ่

และอย่าลืมพิจารณาเคล็ดลับต่อไปนี้สำหรับกระบวนการอัปโหลดแต่ละขั้นตอน การอัปโหลดไบต์ แล้วสร้างรายการสื่อ

การอัปโหลดไบต์

  • การอัปโหลดไบต์ (เพื่อเรียกโทเค็นการอัปโหลด) สามารถทำได้พร้อมกัน
  • ตั้งค่าประเภท MIME ที่ถูกต้องในส่วนหัว X-Goog-Upload-Content-Type เสมอ สำหรับการเรียกการอัปโหลดแต่ละครั้ง

การสร้างรายการสื่อ

  • อย่าโทรออกพร้อมกันกับ batchCreate สำหรับผู้ใช้รายเดียว

    • สำหรับผู้ใช้แต่ละราย ให้โทรหา batchCreate ทีละรายการ (ใน (Serial) )
    • สำหรับผู้ใช้หลายคน ให้โทร batchCreate ครั้งสำหรับผู้ใช้แต่ละราย ต่อกัน เรียกผู้ใช้ที่แตกต่างกันพร้อมกันเท่านั้น

  • ให้NewMediaItemsมากที่สุดเท่าที่จะทำได้ ในการโทรแต่ละครั้งไปยัง batchCreate เพื่อลดจำนวนการโทรทั้งหมดที่คุณมี ในแบบที่จะทำ คุณเพิ่มได้สูงสุด 50 รายการ

  • ตั้งค่าข้อความคำอธิบายที่สื่อความหมาย ที่ผู้ใช้ของคุณสร้างขึ้น อย่าใส่ข้อมูลเมตา เช่น ชื่อไฟล์ แท็กแบบเป็นโปรแกรม หรือข้อความอื่นๆ ที่สร้างขึ้นโดยอัตโนมัติในส่วน คำอธิบาย

ตัวอย่างคำแนะนำแบบทีละขั้น

ตัวอย่างนี้ใช้ Pseudocode เพื่อดำเนินการอัปโหลดรายการสื่อสำหรับหลายรายการ ผู้ใช้ เป้าหมายคือการระบุทั้ง 2 ขั้นตอนของกระบวนการอัปโหลด (การอัปโหลดข้อมูลดิบ ไบต์และการสร้างรายการสื่อ) และ อธิบายแนวทางปฏิบัติแนะนำในการสร้างการอัปโหลดที่มีประสิทธิภาพและยืดหยุ่น การผสานรวม

ขั้นตอนที่ 1: อัปโหลดไบต์ดิบ

ก่อนอื่นให้สร้างคิวเพื่ออัปโหลดไบต์ข้อมูล RAW สำหรับรายการสื่อจาก ผู้ใช้ ติดตามแต่ละรายการที่ส่งคืนแล้ว uploadToken รายการต่อผู้ใช้ สิ่งสำคัญที่ควรทราบมีดังนี้

  • จำนวนชุดข้อความที่อัปโหลดพร้อมกันขึ้นอยู่กับการดำเนินการของคุณ ของคุณ
  • ลองเรียงลำดับคิวการอัปโหลดใหม่ตามที่จำเป็น ตัวอย่างเช่น คุณสามารถ จัดลำดับความสำคัญของการอัปโหลดตามจำนวนการอัปโหลดที่เหลือต่อผู้ใช้ ความคืบหน้าโดยรวมของผู้ใช้ หรือข้อกำหนดอื่นๆ

ซูโดโค้ด

CREATE uploadQueue FROM users, filesToUpload
// Upload media bytes in parallel.
START multiple THREADS
  WHILE uploadQueue is not empty
    POP uploadQueue
    UPLOAD file for user
    GET uploadToken
    CHECK and HANDLE errors
    STORE uploadToken for user in uploadTokensQueue
  END

ขั้นตอนที่ 2: สร้างรายการสื่อ

ในขั้นตอนที่ 1 คุณสามารถอัปโหลดไบต์หลายไบต์จากผู้ใช้หลายคนพร้อมกันได้ แต่ ในขั้นตอนที่ 2 คุณจะใช้การโทรได้ครั้งละ 1 สายเท่านั้น

ซูโดโค้ด

// For each user, create media items once 50 upload tokens have been
// saved, or no more uploads are left per user.
WHEN uploadTokensQueue for user is >= 50 OR no more pending uploads for user
  // Calls can be made in parallel for different users,
  // but only make a single call per user at a time.
  START new thread for (this) user if there is no thread yet
    POP 50 uploadTokens from uploadTokensQueue for user
    CALL mediaItems.batchCreate with uploadTokens
    WAIT UNTIL batchCreate call has completed
    CHECK and HANDLE errors (retry as needed)
  DONE.

ทำขั้นตอนนี้ต่อไปจนกว่าการอัปโหลดและการเรียกใช้การสร้างสื่อทั้งหมดจะเสร็จสมบูรณ์