تحميل وسائط

تتألف عملية تحميل عناصر الوسائط من خطوتين:

  1. يمكنك تحميل وحدات البايت من ملفات الوسائط إلى خادم Google باستخدام نقطة نهاية عمليات التحميل. يؤدي هذا إلى إرجاع رمز مميز للتحميل يحدد وحدات البايت التي تم تحميلها.
  2. استخدِم طلب batchCreate باستخدام الرمز المميّز للتحميل لإنشاء عنصر وسائط في حساب المستخدم على "صور Google".

توضّح هذه الخطوات عملية تحميل ملف وسائط واحد. إذا كنت تحمِّل عدة عناصر وسائط (من المرجّح جدًا لأي تطبيق إنتاجي)، ننصحك بمراجعة أفضل الممارسات المتعلّقة بالتحميل لتحسين كفاءة التحميل.

قبل البدء

نطاقات التفويض المطلوبة

يجب توفير نطاق photoslibrary.appendonly أو photoslibrary لتحميل عناصر الوسائط إلى مكتبة المستخدم أو ألبومه.

يمكن أيضًا إنشاء عناصر الوسائط باستخدام نطاق photoslibrary.sharing. لإنشاء عناصر بنطاق photoslibrary.sharing، يجب أولاً إنشاء ألبوم ووضع علامة عليه بأنّه تمّت مشاركته باستخدام shareAlbum. يمكنك بعد ذلك إنشاء عناصر وسائط تتم مشاركتها مع المستخدم في الألبوم. لا يمكنك إنشاء عناصر مباشرةً في مكتبة المستخدم أو في الألبومات التي لم يشاركها تطبيقك.

عند إدراج الألبومات، تشير السمة isWriteable إلى ما إذا كان بإمكان التطبيق إنشاء وسائط في ألبوم معيّن.

أنواع الملفات وأحجامها المقبولة

يمكنك تحميل أنواع الملفات المدرَجة في الجدول أدناه.

نوع الوسائط أنواع الملفات المقبولة الحد الأقصى لحجم الملف
الصور AVIF وBMP وGIF وHEIC وICO وJPG وPNG وTIFF وWEBP وبعض ملفات RAW. 200 ميغابايت
الفيديوهات 3GP و3G2 وASF وAVI وDIVX وM2T وM2TS وM4V وMKV وMMV وMOD وMOV وMP4 وMPG وMTS وTOD وWMV. 20 غيغابايت

الخطوة 1: تحميل وحدات البايت

تحميل وحدات البايت إلى Google باستخدام طلبات التحميل يعرض طلب التحميل الناجح رمزًا مميزًا للتحميل في شكل سلسلة نصية أولية. استخدِم الرموز المميّزة للتحميل هذه لإنشاء عناصر وسائط من خلال طلب batchCreate

راحة

ضمِّن الحقول التالية في عنوان طلب 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 ميغابايت. تكون الملفات التي يزيد حجمها عن 50 ميغابايت عرضة لمشاكل في الأداء.

تتيح واجهة برمجة التطبيقات لمكتبة صور Google عمليات التحميل القابلة للاستئناف. تتيح لك عملية التحميل القابلة للاستئناف تقسيم ملف الوسائط إلى أقسام متعددة وتحميل قسم واحد في كل مرة.

الخطوة 2: إنشاء ملف وسائط

بعد تحميل وحدات البايت لملفات الوسائط، يمكنك إنشاؤها كعناصر وسائط في "صور Google" باستخدام الرموز المميزة للتحميل. يكون الرمز المميز للتحميل صالحًا لمدة يوم واحد بعد إنشائه. وتتم دائمًا إضافة عنصر وسائط إلى مكتبة المستخدم. لا يمكن إضافة عناصر الوسائط إلى الألبومات إلا التي أنشأها تطبيقك. لمزيد من المعلومات، يُرجى الاطّلاع على نطاقات التفويض.

لإنشاء عناصر وسائط جديدة، يمكنك استدعاء mediaItems.batchCreate من خلال تحديد قائمة newMediaItems. ويحتوي كل newMediaItem على رمز مميّز للتحميل يتم تحديده داخل simpleMediaItem ووصف اختياري يتم عرضه للمستخدم.

يقتصر حقل الوصف على 1000 حرف، ويجب أن يتضمن فقط نصًا مفيدًا أنشأه المستخدمون. على سبيل المثال، "رحلتنا إلى الحديقة" أو "عشاء الأعياد". لا تضمِّن بيانات وصفية مثل أسماء الملفات أو العلامات الآلية أو أي نص آخر يتم إنشاؤه تلقائيًا.

للحصول على أفضل أداء، يمكنك تقليل عدد المكالمات إلى mediaItems.batchCreate التي يتعيّن عليك إجراؤها من خلال تضمين عناصر وسائط متعددة في مكالمة واحدة. انتظِر دائمًا حتى يكتمل الطلب السابق قبل إجراء اتصال لاحق للمستخدم نفسه.

يمكنك إنشاء عنصر وسائط واحد أو عدة عناصر في مكتبة المستخدم من خلال تحديد الأوصاف والرموز المميّزة للتحميل الخاصة بها:

راحة

إليك عنوان طلب 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 ملف وسائط. وستتعذّر طلبات إنشاء عناصر وسائط في ألبوم تتجاوز هذا الحد.

راحة

{
  "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 لإدراج عناصر وسائط في مكان معيّن في الألبوم.

راحة

{
  "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 للطلب. يشير رمز الحالة غير الصفري إلى خطأ.

راحة

إذا تم إنشاء جميع عناصر الوسائط بنجاح، يعرض الطلب حالة 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 على الأقل قبل إعادة المحاولة. استخدم استراتيجية التراجع الأسي عند إعادة محاولة تقديم الطلبات.
    • يحدث 500 خطأ عندما يواجه الخادم خطأ. عند التحميل، يحدث ذلك على الأرجح بسبب إجراء طلبات كتابة متعددة (مثل batchCreate) للمستخدم نفسه في الوقت نفسه. راجِع تفاصيل طلبك ولا تجري اتصالات بـ batchCreate في الوقت نفسه.
  • استخدِم تدفق التحميل القابل للاستئناف لجعل عمليات التحميل أكثر فعالية في حال انقطاع الاتصال بالشبكة، وتقليل استخدام النطاق الترددي من خلال السماح لك باستئناف عمليات التحميل المكتملة جزئيًا. يُعدّ ذلك مهمًا عند التحميل من الأجهزة الجوّالة للعميل أو عند تحميل ملفات كبيرة الحجم.

بالإضافة إلى ذلك، ننصحك باتّباع النصائح التالية لكلّ خطوة من عملية التحميل: تحميل وحدات البايت ثم إنشاء عناصر الوسائط.

جارٍ تحميل وحدات البايت

  • يمكن تحميل وحدات البايت (لاسترداد رموز التحميل) بالتوازي.
  • يجب دائمًا ضبط نوع MIME الصحيح في العنوان X-Goog-Upload-Content-Type لكل مكالمة تحميل.

جارٍ إنشاء ملفات الوسائط

  • لا تُجرِ اتصالات لمستخدم واحد بالتوازي مع batchCreate.

    • لكل مستخدم، عليك إجراء مكالمات مع batchCreate الواحد تلو الآخر (بالتسلسل).
    • بالنسبة إلى عدة مستخدمين، يمكنك دائمًا إجراء مكالمات batchCreate لكل مستخدم واحدًا تلو الآخر. قدِّم طلبات لمستخدمين مختلفين بالتوازي فقط.

  • ننصحك بتضمين أكبر عدد ممكن من NewMediaItems في كل مكالمة إلى الرقم "batchCreate" لتقليل إجمالي عدد المكالمات التي يجب إجراؤها. يمكنك تضمين 50 عنصرًا على الأكثر.

  • اضبط نص وصف مفيدًا أنشأه المستخدمون. لا تضمِّن بيانات وصفية، مثل أسماء الملفات أو العلامات الآلية أو أي نص آخر يتم إنشاؤه تلقائيًا في حقل الوصف.

مثال على جولة تفصيلية

يستخدم هذا المثال الكود الزائف لمتابعة تحميل عناصر الوسائط لعدة مستخدمين. يكمن الهدف في توضيح كلّ من خطوتَي عملية التحميل (تحميل وحدات البايت الأولية وإنشاء عناصر وسائط) وتفصيل أفضل الممارسات لإنشاء عملية دمج فعّالة ومرونة في عملية التحميل.

الخطوة 1: تحميل وحدات البايت الأولية

أنشئ أولاً قائمة انتظار لتحميل وحدات البايت الأولية لعناصر الوسائط من جميع المستخدمين. تتبُّع كل 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: إنشاء ملفات وسائط

في الخطوة الأولى، يمكنك تحميل عدة وحدات بايت من عدة مستخدمين بشكل متوازٍ، ولكن في الخطوة الثانية، يمكنك إجراء مكالمة واحدة فقط لكل مستخدم في الوقت نفسه.

رمز زائف

// 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.

تابِع هذه العملية إلى أن تكتمل جميع عمليات التحميل ومكالمات إنشاء الوسائط.