تحميل وسائط

يتضمّن تحميل عناصر الوسائط خطوتَين:

1. حمِّل وحدات البايت من ملفات الوسائط إلى خادم Google باستخدام نقطة النهاية uploads. تعرض هذه الطريقة رمزًا مميزًا للتحميل يحدّد وحدات البايت التي تم تحميلها.
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 أولاً، ثم يتم عرض الحالة 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: إنشاء عناصر وسائط

في الخطوة 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.

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