Google Drive API به شما امکان میدهد هنگام ایجاد یا بهروزرسانی File
دادههای فایل را آپلود کنید. برای اطلاعات در مورد نحوه ایجاد یک فایل فقط فراداده، مانند یک پوشه، به ایجاد فایلهای فقط فراداده مراجعه کنید.
سه نوع آپلود وجود دارد که می توانید انجام دهید:
آپلود ساده (
uploadType=media
) : از این نوع آپلود برای انتقال یک فایل رسانه ای کوچک (5 مگابایت یا کمتر) بدون ارائه ابرداده استفاده کنید. برای انجام یک آپلود ساده، به انجام آپلود ساده مراجعه کنید.آپلود چند قسمتی (
uploadType=multipart
) : "از این نوع آپلود برای انتقال یک فایل کوچک (5 مگابایت یا کمتر) به همراه ابرداده که فایل را توصیف می کند، در یک درخواست استفاده کنید. برای انجام یک آپلود چند قسمتی، به انجام آپلود چند قسمتی مراجعه کنید.بارگذاری مجدد (
uploadType=resumable
) : از این نوع آپلود برای فایل های بزرگ (بیشتر از 5 مگابایت) و زمانی که احتمال قطع شدن شبکه وجود دارد، مانند هنگام ایجاد یک فایل از یک برنامه تلفن همراه، استفاده کنید. آپلودهای قابل ازسرگیری نیز انتخاب خوبی برای اکثر برنامهها هستند زیرا برای فایلهای کوچک با حداقل هزینه یک درخواست HTTP اضافی در هر بارگذاری کار میکنند. برای انجام آپلود قابل ازسرگیری، به انجام آپلود قابل ازسرگیری مراجعه کنید.
کتابخانه های سرویس گیرنده Google API حداقل یکی از این نوع آپلودها را اجرا می کنند. برای جزئیات بیشتر در مورد نحوه استفاده از هر یک از انواع، به مستندات کتابخانه مشتری مراجعه کنید.
از PATCH
در مقابل PUT
استفاده کنید
به عنوان یک تجدید، فعل HTTP PATCH
از به روز رسانی جزئی منبع فایل پشتیبانی می کند در حالی که فعل HTTP PUT
از جایگزینی کامل منبع پشتیبانی می کند. توجه داشته باشید که PUT
میتواند هنگام افزودن یک فیلد جدید به یک منبع موجود، تغییرات قطعی ایجاد کند.
هنگام آپلود یک منبع فایل، از دستورالعمل های زیر استفاده کنید:
- از فعل HTTP مستند شده در مرجع API برای درخواست اولیه یک آپلود قابل ازسرگیری یا برای تنها درخواست یک آپلود ساده یا چند بخشی استفاده کنید.
- پس از شروع درخواست، از
PUT
برای همه درخواستهای بعدی برای آپلود قابل ازسرگیری استفاده کنید. این درخواست ها صرف نظر از روشی که فراخوانی می شود، محتوا را بارگذاری می کنند.
یک آپلود ساده انجام دهید
برای انجام یک آپلود ساده، از روش files.create
با uploadType=media
استفاده کنید.
موارد زیر نحوه انجام یک آپلود ساده را نشان می دهد:
HTTP
یک درخواست
POST
به URI /upload متد با پارامتر queryuploadType=media
ایجاد کنید:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=media
داده های فایل را به بدنه درخواست اضافه کنید.
این هدرهای HTTP را اضافه کنید:
-
Content-Type
. روی نوع رسانه MIME شیء در حال آپلود تنظیم کنید. -
Content-Length
. تعداد بایت هایی را که آپلود می کنید تنظیم کنید. اگر از رمزگذاری انتقال تکهای استفاده میکنید، این هدر لازم نیست.
-
درخواست را ارسال کنید. در صورت موفقیت آمیز بودن درخواست، سرور کد وضعیت
HTTP 200 OK
را همراه با فراداده فایل برمی گرداند. {HTTP}
هنگامی که یک آپلود ساده انجام می دهید، ابرداده اصلی ایجاد می شود و برخی از ویژگی ها از فایل استنتاج می شوند، مانند نوع MIME یا modifiedTime
. در مواردی که فایل های کوچکی دارید و ابرداده فایل مهم نیست، می توانید از یک آپلود ساده استفاده کنید.
یک بارگذاری چند قسمتی انجام دهید
درخواست آپلود چند قسمتی به شما امکان میدهد ابرداده و داده را در همان درخواست آپلود کنید. اگر دادههایی که ارسال میکنید به اندازهای کوچک هستند که در صورت عدم اتصال، به طور کامل دوباره آپلود شوند، از این گزینه استفاده کنید.
برای انجام آپلود چند قسمتی، از روش files.create
با uploadType=multipart
استفاده کنید.
موارد زیر نحوه انجام آپلود چند قسمتی را نشان می دهد:
جاوا
پایتون
Node.js
PHP
دات نت
HTTP
با پارامتر query
uploadType=multipart
یک درخواستPOST
به /upload URI متد ایجاد کنید:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
بدنه درخواست را ایجاد کنید. بدنه را با توجه به نوع محتوای چندبخشی/مرتبط با RFC 2387 فرمت کنید که شامل دو بخش است:
- فراداده. ابرداده باید ابتدا باشد و باید دارای یک سرصفحه
Content-Type
باشد که رویapplication/json;
charset=UTF-8
. متادیتای فایل را با فرمت JSON اضافه کنید. - رسانه ها رسانه باید در رتبه دوم قرار گیرد و باید یک هدر
Content-Type
از هر نوع MIME داشته باشد. داده های فایل را به بخش رسانه اضافه کنید.
هر قسمت را با یک رشته مرزی که قبل از آن دو خط فاصله وجود دارد، مشخص کنید. علاوه بر این، دو خط فاصله بعد از رشته مرزی نهایی اضافه کنید.
- فراداده. ابرداده باید ابتدا باشد و باید دارای یک سرصفحه
این هدرهای سطح بالای HTTP را اضافه کنید:
-
Content-Type
. رویmultipart/related
تنظیم کنید و رشته مرزی را که برای شناسایی بخشهای مختلف درخواست استفاده میکنید، اضافه کنید. به عنوان مثال: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"
در ابرداده. تماسهای بعدی به files.get
ویژگی fileExtension
فقط خواندنی را برمیگرداند که حاوی پسوندی است که ابتدا در قسمت name
مشخص شده است.
یک بارگذاری مجدد انجام دهید
آپلود قابل ازسرگیری به شما این امکان را می دهد که پس از یک شکست ارتباطی که جریان داده ها را قطع می کند، عملیات آپلود را از سر بگیرید. از آنجایی که مجبور نیستید از ابتدا آپلود فایل های بزرگ را مجددا راه اندازی کنید، در صورت بروز مشکل در شبکه، آپلودهای قابل ازسرگیری نیز می توانند مصرف پهنای باند شما را کاهش دهند.
آپلودهای قابل ازسرگیری زمانی مفید هستند که اندازه فایلهای شما ممکن است بسیار متفاوت باشد یا زمانی که محدودیت زمانی ثابتی برای درخواستها وجود دارد (مانند وظایف پسزمینه سیستم عامل تلفن همراه و درخواستهای خاص App Engine). همچنین میتوانید برای موقعیتهایی که میخواهید نوار پیشرفت آپلود را نشان دهید، از آپلودهای قابل ازسرگیری استفاده کنید.
یک آپلود مجدد شامل چندین مرحله سطح بالا است:
- درخواست اولیه را ارسال کنید و URI جلسه قابل ازسرگیری را بازیابی کنید.
- داده ها را آپلود کنید و وضعیت آپلود را نظارت کنید.
- (اختیاری) اگر آپلود مختل شد، بارگذاری را از سر بگیرید.
درخواست اولیه را ارسال کنید
برای شروع آپلود مجدد، از روش files.create
با uploadType=resumable
استفاده کنید.
HTTP
یک درخواست
POST
به URI /upload متد با پارامتر queryuploadType=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
. اگر متادیتا برای فایل دارید، الزامی است. رویapplication/json;
charset=UTF-8
. -
Content-Length
. لازم است مگر اینکه از رمزگذاری انتقال تکه تکه استفاده کنید. تعداد بایت های موجود در بدنه این درخواست اولیه را تنظیم کنید.
-
درخواست را ارسال کنید. اگر درخواست شروع جلسه با موفقیت انجام شود، پاسخ شامل یک کد وضعیت
200 OK HTTP
است. علاوه بر این، پاسخ شامل یک سرصفحهLocation
است که URI جلسه قابل ازسرگیری را مشخص می کند. برای آپلود داده های فایل و پرس و جو از وضعیت آپلود از URI جلسه قابل تجدید استفاده کنید. URI جلسه قابل ازسرگیری پس از یک هفته منقضی می شود.URL جلسه قابل ازسرگیری را کپی و ذخیره کنید.
به آپلود محتوا ادامه دهید.
محتوا را آپلود کنید
دو راه برای آپلود یک فایل با یک جلسه مجدد وجود دارد:
- آپلود محتوا در یک درخواست : از این روش زمانی استفاده کنید که فایل را می توان در یک درخواست آپلود کرد، اگر محدودیت زمانی ثابتی برای هر درخواست واحد وجود ندارد یا نیازی به نمایش نشانگر پیشرفت آپلود ندارید. این رویکرد بهترین است زیرا به درخواست های کمتری نیاز دارد و عملکرد بهتری را به همراه دارد.
محتوا را در چند تکه آپلود کنید : اگر باید مقدار داده های منتقل شده در هر درخواست را کاهش دهید، از این روش استفاده کنید. ممکن است لازم باشد زمانی که محدودیت زمانی مشخصی برای درخواستهای فردی وجود دارد، انتقال داده را کاهش دهید، همانطور که میتواند در مورد کلاسهای خاصی از درخواستهای App Engine وجود داشته باشد. اگر باید یک نشانگر سفارشی برای نشان دادن پیشرفت آپلود ارائه دهید، این رویکرد نیز مفید است.
HTTP - درخواست تک
- یک درخواست
PUT
به URI جلسه قابل ازسرگیری ایجاد کنید. - داده های فایل را به بدنه درخواست اضافه کنید.
- یک هدر HTTP با طول محتوا اضافه کنید، روی تعداد بایت های فایل تنظیم کنید.
- درخواست را ارسال کنید. اگر درخواست آپلود قطع شد، یا اگر یک پاسخ
5xx
دریافت کردید، رویه را در Resume an interrupted upload دنبال کنید.
HTTP - درخواست های متعدد
یک درخواست
PUT
به URI جلسه قابل ازسرگیری ایجاد کنید.داده های قطعه را به بدنه درخواست اضافه کنید. تکه هایی را در مضرب 256 کیلوبایت (256 x 1024 بایت) در اندازه ایجاد کنید، به جز تکه نهایی که آپلود را کامل می کند. اندازه قطعه را تا حد امکان بزرگ نگه دارید تا آپلود کارآمد باشد.
این هدرهای HTTP را اضافه کنید:
-
Content-Length
. تعداد بایت ها را در قطعه فعلی تنظیم کنید. -
Content-Range
. تنظیم کنید تا نشان دهد کدام بایت ها در فایلی که آپلود می کنید. به عنوان مثال،Content-Range: bytes 0-524287/2000000
نشان می دهد که شما اولین 524288 بایت (256 x 1024 x 2) را در یک فایل 2000000 بایت آپلود می کنید.
-
درخواست را ارسال کنید و پاسخ را پردازش کنید. اگر درخواست آپلود قطع شد، یا اگر یک پاسخ
5xx
دریافت کردید، رویه را در Resume an interrupted upload دنبال کنید.مراحل 1 تا 4 را برای هر تکه ای که در فایل باقی می ماند تکرار کنید. از هدر
Range
در پاسخ برای تعیین اینکه قسمت بعدی را از کجا شروع کنید استفاده کنید. فرض نکنید که سرور تمام بایت های ارسال شده در درخواست قبلی را دریافت کرده است.
هنگامی که کل آپلود فایل کامل شد، یک پاسخ 200 OK
یا 201 Created
را به همراه هر ابرداده مرتبط با منبع دریافت می کنید.
از سرگیری آپلود قطع شده
اگر درخواست آپلود قبل از پاسخ خاتمه یافت، یا اگر پاسخ 503 Service Unavailable
را دریافت کردید، باید آپلود قطع شده را از سر بگیرید.
HTTP
برای درخواست وضعیت آپلود، یک درخواست
PUT
خالی به URI جلسه قابل ازسرگیری ایجاد کنید.یک هدر
Content-Range
اضافه کنید تا مشخص کنید موقعیت فعلی فایل ناشناخته است. برای مثال،Content-Range
روی*/2000000
تنظیم کنید اگر طول کل فایل شما 2000000 بایت باشد. اگر اندازه کامل فایل را نمی دانید،Content-Range
روی*/*
تنظیم کنید.درخواست را ارسال کنید.
پردازش پاسخ:
- پاسخ
200 OK
یا201 Created
نشان می دهد که آپلود کامل شده است و هیچ اقدام دیگری لازم نیست. - پاسخ
308 Resume Incomplete
نشان می دهد که باید به آپلود فایل ادامه دهید. - پاسخ
404 Not Found
نشان می دهد که جلسه آپلود منقضی شده است و آپلود باید از ابتدا دوباره شروع شود.
- پاسخ
اگر یک پاسخ
308 Resume Incomplete
دریافت کردید، هدرRange
پاسخ را پردازش کنید تا مشخص شود سرور کدام بایت را دریافت کرده است. اگر پاسخ هدرRange
نداشته باشد، هیچ بایتی دریافت نشده است. به عنوان مثال، هدرRange
ازbytes=0-42
نشان می دهد که 43 بایت اول فایل دریافت شده است و قسمت بعدی برای آپلود با بایت 44 شروع می شود.اکنون که می دانید کجا آپلود را از سر بگیرید، به آپلود فایل با بایت بعدی ادامه دهید. یک هدر
Content-Range
اضافه کنید تا مشخص کنید کدام قسمت از فایل را ارسال می کنید. به عنوان مثال،Content-Range: bytes 43-1999999
نشان می دهد که شما بایت های 44 تا 2000000 را ارسال می کنید.
خطاهای آپلود رسانه را مدیریت کنید
هنگامی که رسانه را آپلود می کنید، این بهترین شیوه ها را برای رسیدگی به خطاها دنبال کنید:
- برای خطاهای
5xx
، آپلودهایی را که به دلیل قطع اتصال ناموفق هستند، از سر بگیرید یا دوباره امتحان کنید. برای اطلاعات بیشتر در مورد رسیدگی به خطاهای5xx
، به خطاهای 500، 502، 503، 504 مراجعه کنید. - برای خطاهای
403 rate limit
، بارگذاری را دوباره امتحان کنید. برای اطلاعات بیشتر در مورد رسیدگی به خطاهای403 rate limit
، به خطای 403 مراجعه کنید:rateLimitExceeded
. - برای هر گونه خطای
4xx
(از جمله403
) در حین بارگذاری مجدد، بارگذاری را مجدداً راه اندازی کنید. این خطاها نشان می دهد که جلسه آپلود منقضی شده است و باید با درخواست URI جلسه جدید مجدداً راه اندازی شود. جلسات آپلود نیز پس از یک هفته عدم فعالیت منقضی می شود.
وارد کردن به انواع Google Docs
وقتی فایلی را در Drive ایجاد میکنید، ممکن است بخواهید فایل را به یک نوع فایل Google Workspace، مانند Google Docs یا Sheets تبدیل کنید. به عنوان مثال، شاید بخواهید یک سند را از پردازشگر کلمه مورد علاقه خود به یک Docs تبدیل کنید تا از ویژگی های آن استفاده کنید.
برای تبدیل یک فایل به یک نوع فایل Google Workspace خاص، هنگام ایجاد فایل، mimeType
Google Workspace را مشخص کنید.
در زیر نحوه تبدیل یک فایل CSV به صفحه Google Workspace را نشان می دهد:
جاوا
پایتون
Node.js
PHP
دات نت
برای اینکه ببینید آیا یک تبدیل در دسترس است یا نه، قبل از ایجاد فایل، آرایه importFormats
منبع about
را بررسی کنید. تبدیل های پشتیبانی شده به صورت پویا در این آرایه در دسترس هستند. برخی از فرمت های رایج واردات عبارتند از:
از | به |
---|---|
Microsoft Word، OpenDocument Text، HTML، RTF، متن ساده | Google Docs |
Microsoft Excel، صفحه گسترده OpenDocument، CSV، TSV، متن ساده | Google Sheets |
مایکروسافت پاورپوینت، ارائه OpenDocument | اسلایدهای گوگل |
JPEG، PNG، GIF، BMP، PDF | Google Docs (تصویر را در یک سند جاسازی می کند) |
متن ساده (نوع MIME خاص)، JSON | اسکریپت Google Apps |
هنگامی که در طول درخواست update
، رسانه را به فایل Docs، Sheets یا Slides آپلود و تبدیل میکنید، محتوای کامل سند جایگزین میشود.
وقتی تصویری را به Docs تبدیل میکنید، Drive از تشخیص کاراکتر نوری (OCR) برای تبدیل تصویر به متن استفاده میکند. می توانید کیفیت الگوریتم OCR را با تعیین کد زبان BCP 47 قابل اجرا در پارامتر ocrLanguage
بهبود بخشید. متن استخراج شده در Doc در کنار تصویر تعبیه شده ظاهر می شود.
از یک شناسه از پیش تولید شده برای آپلود فایل ها استفاده کنید
Drive API به شما امکان می دهد فهرستی از شناسه های فایل از پیش تولید شده را که برای آپلود و ایجاد منابع استفاده می شود، بازیابی کنید. درخواست های آپلود و ایجاد فایل می توانند از این شناسه های از پیش تولید شده استفاده کنند. فیلد id
را در فراداده فایل تنظیم کنید.
برای ایجاد شناسههای از پیش تولید شده، با تعداد شناسههایی که باید ایجاد کنید، با files.generateIds
تماس بگیرید.
اگر خطای سرور نامشخص یا مهلت زمانی وجود داشت، میتوانید با خیال راحت بارگذاریها را با شناسههای از پیش تولید شده دوباره امتحان کنید. اگر فایل با موفقیت ایجاد شد، تکرارهای بعدی خطای HTTP 409
را برمیگرداند و فایلهای تکراری ایجاد نمیکنند.
متن قابل نمایه سازی را برای انواع فایل های ناشناخته تعریف کنید
کاربران می توانند از رابط کاربری Drive برای یافتن محتوای سند استفاده کنند. همچنین می توانید از files.list
و قسمت fullText
برای جستجوی محتوای برنامه خود استفاده کنید. برای اطلاعات بیشتر، به جستجوی فایلها و پوشهها مراجعه کنید.
Drive بهطور خودکار اسناد را برای جستجو فهرستبندی میکند که نوع فایل را تشخیص میدهد، از جمله اسناد متنی، فایلهای PDF، تصاویر دارای متن، و انواع رایج دیگر. اگر برنامه شما انواع دیگری از فایلها را ذخیره میکند (مانند نقاشیها، ویدیوها و میانبرها)، میتوانید با ارائه متن قابل نمایهسازی در قسمت contentHints.indexableText
فایل، قابلیت شناسایی را بهبود ببخشید.
برای اطلاعات بیشتر درباره متن قابل نمایه سازی، به مدیریت فراداده فایل مراجعه کنید.