تحميل وسائط

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

نظرة عامة

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

ResumableMediaUpload

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

يتم توضيح بروتوكول تحميل الوسائط القابلة للاستئناف، مثلاً في صفحة تحميل الوسائط لواجهة برمجة تطبيقات Drive. تمثّل الفئة الرئيسية موضع الاهتمام 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");