تحميل وسائط

يتم تحميل عناصر الوسائط على مرحلتين:

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

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

قبل البدء

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

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

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

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

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

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

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

upload-token

يُنصح بأن يكون حجم ملف الصور أقل من 50 ميغابايت. الملفات التي يزيد حجمها عن 50 ميغابايت قد تواجه مشاكل في الأداء.

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

الخطوة 2: إنشاء عنصر وسائط

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

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

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

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

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

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

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

يمكنك أيضًا استخدام albumId وalbumPosition ل إدراج عناصر وسائط في موضع محدّد في الألبوم.

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

لمزيد من التفاصيل حول مواضع الصور في الألبومات، يُرجى الاطّلاع على مقالة إضافة محتوى إضافي.

ردّ على إنشاء العنصر

يعرض الاستدعاء mediaItems.batchCreate نتيجة كل عنصر من ملفات الوسائط التي حاولت إنشاءها. تشير قائمة newMediaItemResults إلى الحالة و تتضمن uploadToken للطلب. يشير رمز الحالة غير الصفري إلى خطأ.

{
  "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"
      }
    }
  ]
}

في حال إضافة عنصر بنجاح، يتم عرض mediaItem يحتوي على mediaItemId وproductUrl وmediaMetadata. لمزيد من المعلومات، يُرجى الاطّلاع على مقالة الوصول إلى عناصر الوسائط.

إذا كان عنصر الوسائط فيديو، يجب معالجته أولاً. يحتوي mediaItem على status داخل mediaMetadata يصف حالة processing ملف الفيديو. يعرض الملف الذي تم تحميله حديثًا الحالة PROCESSING أولًا، قبل أن يصبح READY للاستخدام. لمعرفة التفاصيل، يُرجى الاطّلاع على الوصول إلى عناصر الوسائط.

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

يتم عرض النتائج دائمًا بالترتيب نفسه الذي تم فيه إرسال علامات التحميل .

أفضل الممارسات المتعلّقة بالتحميل

تساعدك أفضل الممارسات والمراجع التالية في تحسين كفاءتك العامة في عمليات التحميل:

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

في الخطوة 1، يمكنك تحميل عدة بايتات من مستخدمين متعدّدين بشكل موازٍ، ولكن في الخطوة 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.

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