API Google Диска позволяет загружать данные файла при 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 с параметром запросаuploadType=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
Создайте
POST
запрос к URI метода /upload с параметром запросаuploadType=multipart
:POST https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart
Создайте тело запроса. Отформатируйте тело в соответствии с типом содержимого multipart/based 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 с параметром запроса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
. Требуется, если у вас есть метаданные для файла. Установите значениеapplication/json;
charset=UTF-8
. -
Content-Length
. Требуется, если вы не используете фрагментированное кодирование передачи. Установите количество байтов в теле этого первоначального запроса.
-
Отправьте запрос. Если запрос на инициирование сеанса успешен, ответ включает код состояния
200 OK HTTP
. Кроме того, ответ включает заголовокLocation
, который указывает URI возобновляемого сеанса. Используйте URI возобновляемого сеанса, чтобы загрузить данные файла и запросить статус загрузки. Срок действия URI возобновляемого сеанса истекает через неделю.Скопируйте и сохраните URL-адрес возобновляемого сеанса.
Продолжайте загружать контент .
Загрузите контент
Есть два способа загрузить файл с возобновляемой сессией:
- Загрузить контент одним запросом . Используйте этот подход, если файл можно загрузить одним запросом, если для одного запроса нет фиксированного ограничения по времени или вам не нужно отображать индикатор хода загрузки. Этот подход является лучшим, поскольку он требует меньшего количества запросов и приводит к повышению производительности.
Загружайте контент несколькими частями . Используйте этот подход, если вам необходимо уменьшить объем данных, передаваемых в одном запросе. Возможно, вам придется сократить объем передаваемых данных, если для отдельных запросов установлен фиксированный лимит времени, как это может быть в случае определенных классов запросов App Engine. Этот подход также полезен, если вам необходимо предоставить настраиваемый индикатор, показывающий ход загрузки.
HTTP – одиночный запрос
- Создайте запрос
PUT
к URI возобновляемого сеанса. - Добавьте данные файла в тело запроса.
- Добавьте HTTP-заголовок Content-Length, равный количеству байтов в файле.
- Отправьте запрос. Если запрос на загрузку прерван или вы получили ответ
5xx
, выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» .
HTTP – множественные запросы
Создайте запрос
PUT
к URI возобновляемого сеанса.Добавьте данные чанка в тело запроса. Создавайте фрагменты размером, кратным 256 КБ (256 x 1024 байт), за исключением последнего фрагмента, который завершает загрузку. Сохраняйте размер фрагмента как можно большим, чтобы загрузка была эффективной.
Добавьте эти HTTP-заголовки:
-
Content-Length
. Установите количество байтов в текущем фрагменте. -
Content-Range
. Установите, чтобы показать, какие байты в загружаемом файле. Например,Content-Range: bytes 0-524287/2000000
показывает, что вы загружаете первые 524 288 байт (256 x 1024 x 2) в файл размером 2 000 000 байт.
-
Отправьте запрос и обработайте ответ. Если запрос на загрузку прерван или вы получили ответ
5xx
, выполните процедуру, описанную в разделе «Возобновление прерванной загрузки» .Повторите шаги с 1 по 4 для каждого фрагмента, оставшегося в файле. Используйте заголовок
Range
в ответе, чтобы определить, с чего начать следующий фрагмент. Не предполагайте, что сервер получил все байты, отправленные в предыдущем запросе.
Когда загрузка всего файла будет завершена, вы получите ответ 200 OK
или 201 Created
вместе со всеми метаданными, связанными с ресурсом.
Возобновить прерванную загрузку
Если запрос на загрузку прерывается до получения ответа или если вы получаете ответ 503 Service Unavailable
, вам необходимо возобновить прерванную загрузку.
HTTP
Чтобы запросить статус загрузки, создайте пустой запрос
PUT
для URI возобновляемого сеанса.Добавьте заголовок
Content-Range
чтобы указать, что текущая позиция в файле неизвестна. Например, установитеContent-Range
на*/2000000
если общая длина файла составляет 2 000 000 байт. Если вы не знаете полный размер файла, установите для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 по 2 000 000.
Обработка ошибок загрузки мультимедиа
При загрузке мультимедиа следуйте этим рекомендациям для устранения ошибок:
- При ошибках
5xx
возобновите или повторите загрузку, которая не удалась из-за прерывания соединения. Дополнительную информацию об обработке ошибок5xx
см. в разделах «Ошибки 500, 502, 503, 504» . - Если возникает ошибка
403 rate limit
, повторите загрузку. Дополнительные сведения об обработке ошибок403 rate limit
см. в разделе Ошибка 403:rateLimitExceeded
. - При возникновении любых ошибок
4xx
(включая403
) во время возобновляемой загрузки перезапустите загрузку. Эти ошибки указывают на то, что срок сеанса загрузки истек, и его необходимо перезапустить , запросив новый URI сеанса . Сеансы загрузки также истекают после одной недели бездействия.
Импорт в типы Документов Google
Когда вы создаете файл на Диске, вы можете преобразовать его в тип файла Google Workspace, например Google Docs или Sheets. Например, возможно, вы хотите преобразовать документ из вашего любимого текстового процессора в Документы, чтобы воспользоваться его возможностями.
Чтобы преобразовать файл в определенный тип файла Google Workspace, укажите mimeType
Google Workspace при создании файла.
Ниже показано, как преобразовать файл CSV в лист Google Workspace:
Ява
Питон
Node.js
PHP
.СЕТЬ
Чтобы узнать, доступно ли преобразование, проверьте массив importFormats
about
перед созданием файла. Поддерживаемые преобразования доступны динамически в этом массиве. Некоторые распространенные форматы импорта:
От | К |
---|---|
Microsoft Word, OpenDocument Text, HTML, RTF, обычный текст | Google Документы |
Microsoft Excel, электронная таблица OpenDocument, CSV, TSV, обычный текст | Google Таблицы |
Microsoft PowerPoint, презентация OpenDocument | Google Презентации |
JPEG, PNG, GIF, BMP, PDF | Google Docs (встраивает изображение в документ) |
Обычный текст (специальный тип MIME), JSON | Скрипт Google Apps |
Когда вы загружаете и конвертируете медиафайлы во время запроса update
в файл Документов, Таблиц или Презентаций, заменяется все содержимое документа.
Когда вы конвертируете изображение в Документы, Диск использует оптическое распознавание символов (OCR), чтобы преобразовать изображение в текст. Вы можете улучшить качество алгоритма OCR, указав применимый код языка BCP 47 в параметре ocrLanguage
. Извлеченный текст появится в документе рядом со встроенным изображением.
Используйте заранее сгенерированный идентификатор для загрузки файлов
API Диска позволяет получить список предварительно созданных идентификаторов файлов, которые используются для загрузки и создания ресурсов. Запросы на загрузку и создание файлов могут использовать эти предварительно сгенерированные идентификаторы. Установите поле id
в метаданных файла.
Чтобы создать предварительно сгенерированные идентификаторы, вызовите files.generateIds
, указав количество создаваемых идентификаторов.
Вы можете безопасно повторить загрузку с заранее сгенерированными идентификаторами, если возникла неопределенная ошибка сервера или время ожидания истекло. Если файл был успешно создан, последующие повторные попытки возвращают ошибку HTTP 409
и не создают дубликатов файлов.
Определить индексируемый текст для неизвестных типов файлов
Пользователи могут использовать пользовательский интерфейс Диска для поиска содержимого документа. Вы также можете использовать files.list
и поле fullText
для поиска контента из вашего приложения. Дополнительную информацию см. в разделе Поиск файлов и папок .
Диск автоматически индексирует документы для поиска, когда распознает тип файла, включая текстовые документы, PDF-файлы, изображения с текстом и другие распространенные типы. Если ваше приложение сохраняет файлы других типов (например, рисунки, видео и ярлыки), вы можете улучшить возможность обнаружения, указав индексируемый текст в поле contentHints.indexableText
файла.
Дополнительные сведения об индексируемом тексте см. в разделе Управление метаданными файла .