تحميل وسائط

تتيح العديد من طرق واجهة برمجة التطبيقات تحميل الوسائط بالإضافة إلى نص عادي. في هذه الحالة، يتم تحميل طلب عادي للحصول على Stream إضافي للتحميل.

نظرة عامة

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

ResumableMediaUpload

كانت ميزة "تحميل الوسائط القابلة للاستئناف" متوفّرة في مكتبة برامج Google API .NET العميل منذ الإصدار 1.2.0-beta. تحتوي المكتبات الخاصة بـ Google API على طرق ملائمة للتفاعل مع هذه الميزة.

يمكن الاطّلاع على بروتوكول تحميل الوسائط القابل للاستئناف، على سبيل المثال، في صفحة تحميل الوسائط لواجهة برمجة التطبيقات Drive API. الفئة الرئيسية من الاهتمام هي ResumableUpload في هذه العملية، يتم تحميل محتوى الوسائط على شكل أجزاء.

يبلغ حجم المقطع الافتراضي 10 ميغابايت، ولكن يمكنك تغييره لضبط السمة ChunkSize في الطلب على أي مضاعفات بحجم 256 كيلوبايت. في حال حدوث خطأ في الخادم في أحد الطلبات، سيحدث رقود أسي يُستخدم لإعادة إرسال وحدات البايت التي لم يتم تحميلها بنجاح. بشكل تلقائي، يتم تفعيل الرقود الأسي لكل طلب عميل. يمكنك تغيير السلوك التلقائي عند إنشاء عنصر خدمة جديد من خلال تغيير سمة DefaultExponentialBackOffPolicy في BaseClientService.Initializer و/أو ضبط سمة HttpClientInitializer على تنفيذك الخاص لواجهة IConfigurableHttpClientInitializer التي تضيف بعض سياسة التراجع.

يتم تحديد الطرق التي تتيح تحميل الوسائط في المستندات المرجعية للمستندات الخاصة بواجهة برمجة التطبيقات. بالنسبة إلى طُرق واجهة برمجة التطبيقات هذه، تمت إضافة طُرق الراحة Upload و UploadAsync. تأخذ هذه الطرق Stream المطلوب تحميله ونوع المحتوى كمَعلمات.

احرص على أن يكون موضع البث الذي تحمّله 0، وإلا ستظهر رسالة خطأ مثل "System.invalidOperationException: لم يتم العثور على العنوان المحدَّد".

يُرجى العِلم أنّه بسبب سلوك فئة HttpClient في إطار العمل، يتم طرح TaskCanceledException في حال انتهاء مهلة التحميل. إذا رأيت هذا الاستثناء، ننصحك بزيادة السمة Timeout يدويًا في العميل الذي يستخدمه عنصر الخدمة.

نموذج التعليمات البرمجية

// Create the service using the client credentials.
var service = new DriveService(new BaseClientService.Initializer()
{
    HttpClientInitializer = credential,
    ApplicationName = "Application_Name"
});

using var uploadStream = System.IO.File.OpenRead("Local_File_Name");

// Create the File resource to upload.
Google.Apis.Drive.v3.Data.File driveFile = new Google.Apis.Drive.v3.Data.File
{
    Name = "Drive_File_Name"
};
// Get the media upload request object.
FilesResource.CreateMediaUpload insertRequest = service.Files.Create(
    driveFile, uploadStream, "image/jpeg");

// Add handlers which will be notified on progress changes and upload completion.
// Notification of progress changed will be invoked when the upload was started,
// on each upload chunk, and on success or failure.
insertRequest.ProgressChanged += Upload_ProgressChanged;
insertRequest.ResponseReceived += Upload_ResponseReceived;

await insertRequest.UploadAsync();

static void Upload_ProgressChanged(IUploadProgress progress) =>
    Console.WriteLine(progress.Status + " " + progress.BytesSent);

static void Upload_ResponseReceived(Google.Apis.Drive.v3.Data.File file) =>
    Console.WriteLine(file.Name + " was uploaded successfully");