تحميل وسائط

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

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

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

قبل البدء

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

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

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

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

نوع الوسائط أنواع الملفات المقبولة الحد الأقصى لحجم الملف
الصور 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

حجم الملف المقترَح للصور أقل من 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"
      }
    }
   , ...
  ]
}

يمكنك أيضًا تحديد 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 للطلب. يشير رمز الحالة غير الصفري إلى خطأ.

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

في حال إضافة عنصر بنجاح، يتم عرض 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، يمكنك تحميل عدة وحدات بايت من مستخدمين متعددين بشكل متوازٍ، ولكن بشكل الخطوة الثانية، يمكنك إجراء مكالمة واحدة فقط لكل مستخدم في المرة الواحدة.

رمز زائف

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

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