API گوگل درایو به شما امکان میدهد هنگام ایجاد یا بهروزرسانی یک File دادههای فایل را آپلود کنید. برای اطلاعات بیشتر در مورد نحوه ایجاد یک فایل فقط فراداده، مانند یک پوشه، به بخش ایجاد فایلهای فقط فراداده مراجعه کنید.
سه نوع آپلود وجود دارد که میتوانید انجام دهید:
آپلود ساده (
uploadType=media) : از این نوع آپلود برای انتقال یک فایل رسانهای کوچک (۵ مگابایت یا کمتر) بدون ارائه فراداده استفاده کنید. برای انجام آپلود ساده، به انجام آپلود ساده مراجعه کنید.آپلود چندبخشی (
uploadType=multipart) : "از این نوع آپلود برای انتقال یک فایل کوچک (5 مگابایت یا کمتر) به همراه فرادادهای که فایل را توصیف میکند، در یک درخواست واحد استفاده کنید. برای انجام آپلود چندبخشی، به انجام آپلود چندبخشی مراجعه کنید."آپلود از سرگیریپذیر (
uploadType=resumable) : از این نوع آپلود برای فایلهای بزرگ (بزرگتر از ۵ مگابایت) و زمانی که احتمال قطع شبکه زیاد است، مانند هنگام ایجاد فایل از یک برنامه تلفن همراه، استفاده کنید. آپلودهای از سرگیریپذیر همچنین انتخاب خوبی برای اکثر برنامهها هستند زیرا برای فایلهای کوچک نیز با حداقل هزینه یک درخواست HTTP اضافی برای هر آپلود کار میکنند. برای انجام آپلود از سرگیریپذیر، به انجام آپلود از سرگیریپذیر مراجعه کنید.
کتابخانههای کلاینت API گوگل حداقل یکی از این نوع آپلودها را پیادهسازی میکنند. برای جزئیات بیشتر در مورد نحوه استفاده از هر یک از این انواع، به مستندات کتابخانه کلاینت مراجعه کنید.
استفاده از PUT در مقابل PATCH
به عنوان یادآوری، فعل HTTP PATCH از بهروزرسانی جزئی منبع فایل پشتیبانی میکند در حالی که فعل HTTP PUT از جایگزینی کامل منبع پشتیبانی میکند. توجه داشته باشید که PUT میتواند هنگام اضافه کردن یک فیلد جدید به یک منبع موجود، تغییرات جزئی ایجاد کند.
هنگام آپلود فایل، از دستورالعملهای زیر استفاده کنید:
- برای درخواست اولیه آپلود قابل از سرگیری یا برای تنها درخواست آپلود ساده یا چند قسمتی، از فعل HTTP مستند شده در مرجع API استفاده کنید.
-
PUTبرای همه درخواستهای بعدی برای آپلود قابل از سرگیری پس از شروع درخواست استفاده کنید. این درخواستها صرف نظر از متدی که فراخوانی میشود، محتوا را آپلود میکنند.
انجام یک آپلود ساده
برای انجام یک آپلود ساده، از متد create روی منبع files با uploadType=media استفاده کنید.
در زیر نحوه انجام یک آپلود ساده نشان داده شده است:
اچتیپی
یک درخواست
POSTبه آدرس /upload متد با پارامتر کوئریuploadType=mediaایجاد کنید:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=mediaدادههای فایل را به بدنه درخواست اضافه کنید.
این هدرهای HTTP را اضافه کنید:
-
Content-Type): نوع رسانه MIME شیء در حال آپلود را تنظیم میکند. -
Content-Length. روی تعداد بایتهایی که آپلود میکنید تنظیم میشود. اگر از کدگذاری انتقال تکهای (chunked transfer encoding) استفاده میکنید، این هدر لازم نیست.
-
درخواست را ارسال کنید. اگر درخواست موفقیتآمیز باشد، سرور کد وضعیت
HTTP 200 OKرا به همراه فرادادههای فایل برمیگرداند. {HTTP}
وقتی یک آپلود ساده انجام میدهید، متادیتای اولیه ایجاد میشود و برخی ویژگیها از فایل استنباط میشوند، مانند نوع MIME یا modifiedTime . میتوانید در مواردی که فایلهای کوچکی دارید و متادیتای فایل مهم نیست، از آپلود ساده استفاده کنید.
انجام آپلود چند قسمتی
درخواست آپلود چندبخشی به شما امکان میدهد ابرداده و دادهها را در یک درخواست آپلود کنید. اگر دادههایی که ارسال میکنید به اندازهای کوچک هستند که در صورت قطع اتصال، میتوان دوباره آنها را به طور کامل آپلود کرد، از این گزینه استفاده کنید.
برای انجام آپلود چندبخشی، از متد create روی منبع files با uploadType=multipart استفاده کنید.
در ادامه نحوه انجام آپلود چند قسمتی نشان داده شده است:
جاوا
پایتون
نود جی اس
پی اچ پی
دات نت
اچتیپی
یک درخواست
POSTبه آدرس /upload متد با پارامتر کوئریuploadType=multipartایجاد کنید:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipartبدنه درخواست را ایجاد کنید. بدنه را مطابق با نوع محتوای چندبخشی/مرتبط RFC 2387 قالببندی کنید، که شامل دو بخش است:
- فراداده. فراداده باید اول بیاید و باید سرآیند
Content-Typeheader) آن رویapplication/json;charset=UTF-8تنظیم شده باشد. فراداده فایل را با فرمت JSON اضافه کنید. - رسانه. رسانه باید در جایگاه دوم قرار گیرد و باید دارای سرآیند
Content-Typeاز هر نوع MIME باشد. دادههای فایل را به بخش رسانه اضافه کنید.
هر بخش را با یک رشته مرزی مشخص کنید که قبل از آن دو خط تیره قرار دارد. علاوه بر این، دو خط تیره بعد از آخرین رشته مرزی اضافه کنید.
- فراداده. فراداده باید اول بیاید و باید سرآیند
این هدرهای HTTP سطح بالا را اضافه کنید:
-
Content-Type. رویmultipart/relatedتنظیم کنید و رشته مرزی (boundary string) که برای شناسایی بخشهای مختلف درخواست استفاده میکنید را نیز در آن قرار دهید. برای مثال:Content-Type: multipart/related; boundary=foo_bar_baz -
Content-Length. تعداد کل بایتهای موجود در بدنه درخواست را تنظیم میکند.
-
درخواست را ارسال کنید.
برای ایجاد یا بهروزرسانی بخش فراداده، بدون دادههای مرتبط، یک درخواست POST یا PATCH به نقطه پایانی منبع استاندارد ارسال کنید: https://www.googleapis.com/drive/v3/files اگر درخواست موفقیتآمیز باشد، سرور کد وضعیت HTTP 200 OK را به همراه فراداده فایل برمیگرداند.
هنگام ایجاد فایلها، باید پسوند فایل را در فیلد name فایل مشخص کنید. برای مثال، هنگام ایجاد یک فایل JPEG عکس، میتوانید چیزی شبیه به "name": "photo.jpg" را در متادیتا مشخص کنید. فراخوانیهای بعدی به متد get ، خاصیت fileExtension فقط خواندنی را برمیگرداند که حاوی پسوندی است که در ابتدا در فیلد name مشخص شده است.
انجام آپلود با قابلیت از سرگیری
آپلود قابل از سرگیری به شما امکان میدهد عملیات آپلود را پس از قطع شدن جریان دادهها به دلیل قطع ارتباط، از سر بگیرید. از آنجا که لازم نیست آپلود فایلهای بزرگ را از ابتدا دوباره شروع کنید، آپلودهای قابل از سرگیری میتوانند در صورت بروز مشکل در شبکه، استفاده از پهنای باند شما را نیز کاهش دهند.
آپلودهای قابل از سرگیری زمانی مفید هستند که اندازه فایلهای شما ممکن است بسیار متفاوت باشد یا زمانی که محدودیت زمانی ثابتی برای درخواستها وجود دارد (مانند وظایف پسزمینه سیستم عامل موبایل و درخواستهای خاص موتور برنامه). همچنین میتوانید از آپلودهای قابل از سرگیری برای موقعیتهایی که میخواهید نوار پیشرفت آپلود را نشان دهید، استفاده کنید.
آپلود قابل از سرگیری شامل چندین مرحله سطح بالا است:
- درخواست اولیه را ارسال کنید و URI جلسه قابل از سرگیری را بازیابی کنید.
- دادهها را آپلود کنید و وضعیت آپلود را زیر نظر داشته باشید.
- (اختیاری) اگر آپلود با مشکل مواجه شد، آپلود را از سر بگیرید.
ارسال درخواست اولیه
برای شروع آپلود با قابلیت از سرگیری، از متد create روی منبع files با uploadType=resumable استفاده کنید.
اچتیپی
یک درخواست
POSTبه آدرس /upload متد با پارامتر کوئریuploadType=resumableایجاد کنید:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=resumableاگر درخواست شروع موفقیتآمیز باشد، پاسخ شامل یک کد وضعیت HTTP
200 OKاست. علاوه بر این، شامل یک هدرLocationاست که URI مربوط به جلسه قابل از سرگیری را مشخص میکند:HTTP/1.1 200 OK Location: https://www.googleapis.com/upload/drive/v3/files?uploadType=resumable&upload_id=xa298sd_sdlkj2 Content-Length: 0آدرس اینترنتی (URI) جلسه قابل از سرگیری را ذخیره کنید تا بتوانید دادههای فایل را آپلود کرده و وضعیت آپلود را بررسی کنید. یک آدرس اینترنتی (URI) جلسه قابل از سرگیری پس از یک هفته منقضی میشود.
اگر برای فایل، متادیتا دارید، آن را با فرمت JSON به بدنه درخواست اضافه کنید. در غیر این صورت، بدنه درخواست را خالی بگذارید.
این هدرهای HTTP را اضافه کنید:
-
X-Upload-Content-Type. اختیاری. نوع MIME دادههای فایل را که در درخواستهای بعدی منتقل میشوند، تنظیم میکند. اگر نوع MIME دادهها در متادیتا یا از طریق این هدر مشخص نشده باشد، شیء به صورتapplication/octet-stream. -
X-Upload-Content-Length. اختیاری. روی تعداد بایتهای داده فایل که در درخواستهای بعدی منتقل میشوند، تنظیم میشود. -
Content-Type. اگر برای فایل، فراداده (metadata) دارید، الزامی است. رویapplication/json;charset=UTF-8تنظیم کنید. -
Content-Length. مگر اینکه از کدگذاری انتقال تکهای استفاده کنید، الزامی است. روی تعداد بایتهای موجود در بدنه این درخواست اولیه تنظیم کنید.
-
درخواست را ارسال کنید. اگر درخواست شروع جلسه موفقیتآمیز باشد، پاسخ شامل یک کد وضعیت
200 OK HTTP. علاوه بر این، پاسخ شامل یک هدرLocationاست که URI جلسه قابل از سرگیری را مشخص میکند. از URI جلسه قابل از سرگیری برای آپلود دادههای فایل و پرس و جو در مورد وضعیت آپلود استفاده کنید. URI جلسه قابل از سرگیری پس از یک هفته منقضی میشود.آدرس اینترنتی (URL) جلسه قابل از سرگیری را کپی و ذخیره کنید.
به بارگذاری محتوا ادامه دهید.
محتوا را بارگذاری کنید
دو روش برای آپلود فایل با قابلیت از سرگیری جلسه وجود دارد:
- بارگذاری محتوا در یک درخواست واحد : زمانی از این رویکرد استفاده کنید که فایل بتواند در یک درخواست بارگذاری شود، محدودیت زمانی ثابتی برای هر درخواست واحد وجود نداشته باشد، یا نیازی به نمایش نشانگر پیشرفت بارگذاری نداشته باشید. این رویکرد بهترین گزینه است زیرا به درخواستهای کمتری نیاز دارد و منجر به عملکرد بهتری میشود.
محتوا را در چند بخش بارگذاری کنید : اگر باید میزان دادههای منتقل شده در هر درخواست واحد را کاهش دهید، از این رویکرد استفاده کنید. ممکن است لازم باشد دادههای منتقل شده را کاهش دهید، زمانی که محدودیت زمانی ثابتی برای درخواستهای فردی وجود دارد، همانطور که میتواند برای دستههای خاصی از درخواستهای App Engine اتفاق بیفتد. این رویکرد همچنین در صورتی مفید است که باید یک نشانگر سفارشی برای نشان دادن پیشرفت بارگذاری ارائه دهید.
HTTP - درخواست واحد
- یک درخواست
PUTبه آدرس URL قابل از سرگیری جلسه ایجاد کنید. - دادههای فایل را به بدنه درخواست اضافه کنید.
- یک هدر HTTP با طول محتوا (Content-Length) اضافه کنید که روی تعداد بایتهای موجود در فایل تنظیم شده باشد.
- درخواست را ارسال کنید. اگر درخواست آپلود قطع شد، یا اگر پاسخ
5xxدریافت کردید، روش موجود در «از سرگیری آپلود قطع شده» را دنبال کنید.
HTTP - درخواستهای چندگانه
یک درخواست
PUTبه آدرس URL قابل از سرگیری جلسه ایجاد کنید.دادههای تکه را به بدنه درخواست اضافه کنید. تکههایی با اندازه مضربی از ۲۵۶ کیلوبایت (۲۵۶ × ۱۰۲۴ بایت) ایجاد کنید، به جز تکه آخر که آپلود را کامل میکند. اندازه تکه را تا حد امکان بزرگ نگه دارید تا آپلود کارآمد باشد.
این هدرهای HTTP را اضافه کنید:
-
Content-Length. تعداد بایتهای موجود در قطعه فعلی را تنظیم میکند. -
Content-Range). این گزینه را تنظیم کنید تا نشان دهد کدام بایتها در فایلی که آپلود میکنید وجود دارد. برای مثال،Content-Range: bytes 0-524287/2000000نشان میدهد که شما 524,288 بایت اول (256 x 1024 x 2) را در یک فایل 2,000,000 بایتی آپلود میکنید.
-
درخواست را ارسال کنید و پاسخ را پردازش کنید. اگر درخواست آپلود قطع شد، یا اگر پاسخی با طول
5xxدریافت کردید، روش موجود در «از سرگیری آپلود قطع شده» را دنبال کنید.مراحل ۱ تا ۴ را برای هر تکهای که در فایل باقی مانده است تکرار کنید. از سرآیند
Rangeدر پاسخ برای تعیین محل شروع تکه بعدی استفاده کنید. فرض نکنید که سرور تمام بایتهای ارسال شده در درخواست قبلی را دریافت کرده است.
وقتی کل آپلود فایل کامل شد، شما یک پاسخ 200 OK یا 201 Created به همراه هرگونه فراداده مرتبط با منبع دریافت میکنید.
از سرگیری آپلود متوقف شده
اگر درخواست آپلود قبل از دریافت پاسخ خاتمه یابد، یا اگر خطای 503 Service Unavailable را دریافت کنید، باید آپلود متوقف شده را از سر بگیرید.
اچتیپی
برای درخواست وضعیت آپلود، یک درخواست
PUTخالی به URI جلسه قابل از سرگیری ایجاد کنید.یک سربرگ
Content-Rangeاضافه کنید تا نشان دهد موقعیت فعلی در فایل ناشناخته است. برای مثال، اگر طول کل فایل شما ۲،۰۰۰،۰۰۰ بایت استContent-Rangeرا روی*/2000000تنظیم کنید. اگر اندازه کامل فایل را نمیدانید،Content-Rangeروی*/*تنظیم کنید.درخواست را ارسال کنید.
پردازش پاسخ:
- پاسخ
200 OKیا201 Createdنشان میدهد که آپلود با موفقیت انجام شده است و هیچ اقدام دیگری لازم نیست. - پاسخ
308 Resume Incompleteنشان میدهد که شما باید به آپلود فایل ادامه دهید. - خطای
404 Not Foundنشان میدهد که جلسه آپلود منقضی شده است و آپلود باید از ابتدا دوباره شروع شود.
- پاسخ
اگر پاسخ
308 Resume Incompleteدریافت کردید، سرآیندRangeپاسخ را پردازش کنید تا مشخص شود سرور کدام بایتها را دریافت کرده است. اگر پاسخ سرآیندRangeنداشته باشد، هیچ بایتی دریافت نشده است. برای مثال، سرآیندRangebytes=0-42نشان میدهد که 43 بایت اول فایل دریافت شده است و بخش بعدی برای آپلود با بایت 44 شروع میشود.حالا که میدانید آپلود را از کجا از سر بگیرید، آپلود فایل را از بایت بعدی شروع کنید. یک سربرگ
Content-Rangeاضافه کنید تا مشخص شود کدام بخش از فایل را ارسال میکنید. برای مثال،Content-Range: bytes 43-1999999نشان میدهد که شما بایتهای ۴۴ تا ۲۰۰۰۰۰۰ را ارسال میکنید.
مدیریت خطاهای آپلود رسانه
هنگام آپلود رسانه، برای مدیریت خطاها، این بهترین شیوهها را دنبال کنید:
- برای خطاهای
5xx، آپلودهایی که به دلیل قطع اتصال با شکست مواجه میشوند را از سر بگیرید یا دوباره امتحان کنید. برای اطلاعات بیشتر در مورد مدیریت خطاهای5xx، به خطاهای 500، 502، 503، 504 مراجعه کنید. - برای خطاهای
403 rate limit، آپلود را دوباره امتحان کنید. برای اطلاعات بیشتر در مورد مدیریت خطاهای403 rate limit، به خطای ۴۰۳:rateLimitExceededمراجعه کنید. - برای هرگونه خطای
4xx(از جمله403) در طول آپلود قابل از سرگیری، آپلود را مجدداً راهاندازی کنید. این خطاها نشان میدهند که جلسه آپلود منقضی شده است و باید با درخواست یک URI جلسه جدید مجدداً راهاندازی شود. جلسات آپلود نیز پس از یک هفته عدم فعالیت منقضی میشوند.
انواع داده را به Google Docs وارد کنید
وقتی فایلی را در درایو ایجاد میکنید، ممکن است بخواهید آن را به یک نوع فایل Google Workspace مانند Google Docs یا Sheets تبدیل کنید. به عنوان مثال، شاید بخواهید یک سند را از پردازشگر متن مورد علاقه خود به Docs تبدیل کنید تا از ویژگیهای آن بهرهمند شوید.
برای تبدیل یک فایل به یک نوع فایل خاص Google Workspace، هنگام ایجاد فایل، mimeType Google Workspace را مشخص کنید.
در ادامه نحوه تبدیل فایل CSV به برگه Google Workspace نشان داده شده است:
جاوا
پایتون
نود جی اس
پی اچ پی
دات نت
برای بررسی اینکه آیا تبدیلی در دسترس است یا خیر، قبل از ایجاد فایل، فیلد importFormats از منبع about را بررسی کنید. تبدیلهای پشتیبانیشده بهصورت پویا در این آرایه در دسترس هستند. برخی از قالبهای رایج برای وارد کردن عبارتند از:
| از | به |
|---|---|
| مایکروسافت ورد، متن سند باز، HTML، RTF، متن ساده | اسناد گوگل |
| مایکروسافت اکسل، صفحه گسترده OpenDocument، CSV، TSV، متن ساده | صفحات گوگل |
| مایکروسافت پاورپوینت، ارائه متن باز | اسلایدهای گوگل |
| JPEG، PNG، GIF، BMP، PDF | اسناد گوگل (تصویر را در یک سند جاسازی میکند) |
| متن ساده (نوع MIME ویژه)، JSON | اسکریپت برنامههای گوگل |
وقتی در طول درخواست update ، رسانه را آپلود و به فایل Docs، Sheets یا Slides تبدیل میکنید، کل محتوای سند جایگزین میشود.
وقتی تصویری را به سند تبدیل میکنید، درایو از تشخیص نوری کاراکتر (OCR) برای تبدیل تصویر به متن استفاده میکند. میتوانید کیفیت الگوریتم OCR را با مشخص کردن کد زبان BCP 47 مربوطه در پارامتر ocrLanguage بهبود بخشید. متن استخراج شده در سند در کنار تصویر جاسازی شده ظاهر میشود.
برای آپلود فایلها از یک شناسه از پیش تولید شده استفاده کنید
رابط برنامهنویسی کاربردی درایو (Drive API) به شما امکان میدهد فهرستی از شناسههای فایل از پیش تولید شده را بازیابی کنید که میتوانند برای ایجاد، کپی و آپلود منابع استفاده شوند. برای اطلاعات بیشتر، به بخش «شناسههای تولید شده برای استفاده با فایلهایتان» مراجعه کنید.
در صورت بروز خطای نامشخص سرور یا اتمام زمان، میتوانید با خیال راحت آپلودها را با شناسههای از پیش تولید شده دوباره امتحان کنید. اگر عملیات فایل موفقیتآمیز باشد، تلاشهای بعدی با کد وضعیت HTTP 409 Conflict مواجه میشوند و فایلهای تکراری ایجاد نمیشوند.
توجه داشته باشید که شناسههای از پیش تولید شده برای ایجاد فایلهای Google Workspace پشتیبانی نمیشوند، به جز انواع MIME مربوط به application/vnd.google-apps.drive-sdk و application/vnd.google-apps.folder . به طور مشابه، آپلودهایی که به تبدیل به فرمت فایل Google Workspace اشاره میکنند، پشتیبانی نمیشوند.
تعریف متن قابل فهرستبندی برای انواع فایلهای ناشناخته
کاربران میتوانند از رابط کاربری Drive برای یافتن محتوای سند استفاده کنند. همچنین میتوانید از متد list در منبع files و فیلد fullText برای جستجوی محتوا از برنامه خود استفاده کنید. برای اطلاعات بیشتر، به بخش «جستجوی فایلها و پوشهها» مراجعه کنید.
درایو به طور خودکار اسناد را برای جستجو فهرست میکند وقتی نوع فایل، از جمله اسناد متنی، PDFها، تصاویر دارای متن و سایر انواع رایج را تشخیص دهد. اگر برنامه شما انواع دیگری از فایلها (مانند نقاشیها، ویدیو و میانبرها) را ذخیره میکند، میتوانید با ارائه متن قابل فهرستبندی در فیلد contentHints.indexableText فایل، قابلیت کشف آن را بهبود بخشید.
برای اطلاعات بیشتر در مورد متن قابل فهرستبندی، به مدیریت فراداده فایل مراجعه کنید.