Uploads: binary-safe multipart uploads for small files, resumable
uploads (chunked, with status query and resume) for large ones, and
content replacement for existing files. upload-file and
update-file-content switch to resumable automatically above 5 MiB.
Content may be Bytes (sent verbatim), a Str (its UTF-8 bytes), or a Map/Vec (sent as JSON). Bodies are assembled as Bytes, so binary data (0x00, 0xFF, invalid UTF-8) arrives intact.
Resumable uploads. A session is opened with
start-resumable-upload, then content is PUT in chunks that are
multiples of 256 KiB (default 8 MiB, opts.chunk-size). After each
chunk, Drive's 308 Resume Incomplete says how much it has stored
(its Range header), and the next chunk starts from there. When a
chunk fails with 429/5xx or a dropped connection, the upload asks Drive
for the stored offset (upload-status) and carries on from it, once,
at once (google-core never waits; use a run retry policy for
backoff). Sessions stay valid for a week; resume-upload continues an
interrupted one, in this run or a later one.
A session URI is sent the call's credentials, so it must be a Google
URL (or under google.drive.api-root) unless opts has its own
credential: context credentials never go to another host.
Scopes. drive by default; drive.file is enough to create files
and to update files the app created.
Values
CHUNK_ALIGN
CHUNK_ALIGN: Int 262144
CONVERT_TARGETS
CONVERT_TARGETS: Map {
document: "application/vnd.google-apps.document",
doc: "application/vnd.google-apps.document",
spreadsheet: "application/vnd.google-apps.spreadsheet",
sheet: "application/vnd.google-apps.spreadsheet",
presentation: "application/vnd.google-apps.presentation",
slides: "application/vnd.google-apps.presentation"
}
DEFAULT_CHUNK_SIZE
DEFAULT_CHUNK_SIZE: Int 8388608
GOOGLE_SESSION_URI_PATTERN
GOOGLE_SESSION_URI_PATTERN: Str "^https://[A-Za-z0-9.-]+\\.googleapis\\.com/"
RESUMABLE_THRESHOLD
RESUMABLE_THRESHOLD: Int 5242880
UPLOAD_LOCAL_KEYS
UPLOAD_LOCAL_KEYS: Vec [
"parent",
"parents",
"description",
"metadata",
"resumable",
"chunk-size",
"convert-to",
"file-id"
]
Functions
align-chunk-size
fn (size: Int): Int
Round a chunk size down to a multiple of 256 KiB (Drive's requirement for every chunk but the last), at least 256 KiB.
Example
::google::drive::upload/align-chunk-size(1000000) // 786432
::google::drive::upload/align-chunk-size(1) // 262144
build-multipart
fn (metadata: Map, content: Any, mime-type: Str, boundary: Str): Bytes
Build a multipart/related upload body as Bytes: a JSON metadata
part (nulls dropped) and the content part, separated by boundary.
Content is concatenated as bytes, never interpolated into a string,
so binary payloads survive.
Example
body ::google::drive::upload/build-multipart({name: "a.txt"}, "hi", "text/plain", "b1")
contains(Str(body), "Content-Type: text/plain") // true
ends-with(Str(body), "--b1--\r\n") // true
chunk-bounds
fn (offset: Int, chunk-size: Int, total: Int): Vec
The [start, end) of the chunk beginning at offset (pure): end is
offset + chunk-size, capped at total.
Example
::google::drive::upload/chunk-bounds(0, 8, 20) // [0, 8]
::google::drive::upload/chunk-bounds(16, 8, 20) // [16, 20]
classify-upload-response
fn (response: Result): Map
Interpret the response to a resumable-upload PUT (pure): returns
{state: "complete", file}, {state: "incomplete", next-offset}
(from the Range header of a 308), or {state: "retry", error} for
failures worth another try (error is what to err if there are no
tries left: an HttpError or a transport message), or an Err (expired
session, other 4xx).
Example
::google::drive::upload/classify-upload-response({status: 308, headers: {range: "bytes=0-42"}})
// {state: "incomplete", next-offset: 43}
::google::drive::upload/classify-upload-response({status: 200, body: {id: "1AbC"}})
// {state: "complete", file: {id: "1AbC"}}
content-range
fn (start: Int, end: Int, total: Int): Str
The Content-Range for sending bytes start up to (not including)
end of a total-byte upload: content-range(0, 524288, 2000000) is
"bytes 0-524287/2000000". An empty range (start = end) is the
status query form "bytes */<total>".
Example
::google::drive::upload/content-range(0, 524288, 2000000) // "bytes 0-524287/2000000"
::google::drive::upload/content-range(2000000, 2000000, 2000000) // "bytes */2000000"
convert-target
fn (value: Any): Str?
The Google-native MIME type to convert an upload into:
"document"/"doc", "spreadsheet"/"sheet",
"presentation"/"slides", or a full MIME type. Null means no
conversion.
Example
::google::drive::upload/convert-target("sheet") // "application/vnd.google-apps.spreadsheet"
::google::drive::upload/convert-target(null) // null
new-boundary
fn (): Str
A random multipart boundary, so file content cannot collide with it.
Example
starts-with(::google::drive::upload/new-boundary(), "hot-drive-") // true
next-offset-from-range
fn (range: Str?): Int
The next byte to send after a 308 Resume Incomplete, from its Range
header: "bytes=0-42" means 43. No header means nothing was stored (0).
Example
::google::drive::upload/next-offset-from-range("bytes=0-42") // 43
::google::drive::upload/next-offset-from-range(null) // 0
resume-upload
fn (session-uri: Str, content: Any): Map
fn (session-uri: Str, content: Any, opts: Map): Map
Continue an interrupted resumable upload of content (the same bytes
as before): ask Drive for the stored offset and send the rest. Returns
the file resource, straight away if Drive already has every byte. An
expired session (sessions last a week) is an Err: start a new upload.
bytes Bytes("report contents")
session ::google::drive::upload/start-resumable-upload({name: "big.bin"}, "application/octet-stream", length(bytes))
// ... store `session`; the upload is interrupted ...
file ::google::drive::upload/resume-upload(session, bytes)
session-uri-error
fn (session-uri: Str, opts: Map): Str?
Why session-uri may not be used with these opts, or null: it is a
Google URL or under google.drive.api-root, or opts has its own
credential. Context credentials are never sent to any other URL.
Example
::google::drive::upload/session-uri-error("https://www.googleapis.com/upload/drive/v3/files?upload_id=abc", {}) // null
is-some(::google::drive::upload/session-uri-error("https://example.com/session", {})) // true
start-resumable-upload
fn (metadata: Map, mime-type: Str, size: Int): Str
fn (metadata: Map, mime-type: Str, size: Int, opts: Map): Str
POST (or PATCH, with opts.file-id) /upload/drive/v3/files?uploadType=resumable
- open a resumable session for
sizebytes ofmime-typewith the given filemetadata. Returns the session URI (fromLocation); store it to resume later.
Example
session ::google::drive::upload/start-resumable-upload({name: "video.mp4"}, "video/mp4", 52428800)
// A new version of an existing file
::google::drive::upload/start-resumable-upload({}, "video/mp4", 52428800, {file-id: "1AbCfile"})
to-bytes
fn (content: Any): Bytes
Upload content as Bytes: Bytes pass through, a Str becomes its UTF-8 bytes, null is empty, and anything else is JSON-encoded.
Example
length(::google::drive::upload/to-bytes("héllo")) // 6
Str(::google::drive::upload/to-bytes({a: 1})) // "{\"a\":1}"
update-file-content
fn (id: Str, content: Any, mime-type: Str): Map
fn (id: Str, content: Any, mime-type: Str, opts: Map): Map
PATCH /upload/files/{id} - replace a file's content (a new revision),
optionally changing metadata via opts.metadata / description.
Resumable above 5 MiB. Returns the file resource.
Example
file ::google::drive::upload/update-file-content("1AbCfile", "name,total\nAda,3\n", "text/csv")
file.version
// Also change the description
::google::drive::upload/update-file-content("1AbCfile", "{}", "application/json", {description: "Nightly export"})
upload-file
fn (name: Str, content: Any, mime-type: Str): Map
fn (name: Str, content: Any, mime-type: Str, parent: Str): Map
fn (name: Str, content: Any, mime-type: Str, opts: Map): Map
Create a file with content. A Str fourth argument is the parent folder
id; an opts Map takes parent/parents, description, metadata
(extra fields such as appProperties), convert-to ("document",
"spreadsheet", "presentation": convert on upload, e.g. a .docx or
.csv into a Google Doc/Sheet), resumable: true to force a resumable
upload, chunk-size, Drive parameters (keepRevisionForever,
ocrLanguage, useContentAsIndexableText, fields) and
credentials. Returns the file resource.
folder-id "1AbCfolder"
csv-text "name,total\nAda,3\n"
file ::google::drive::upload/upload-file("report.csv", csv-text, "text/csv", folder-id)
sheet ::google::drive::upload/upload-file("report", csv-text, "text/csv", {parent: folder-id, convert-to: "spreadsheet"})
upload-resumable
fn (session-uri: Str, content: Any): Map
fn (session-uri: Str, content: Any, opts: Map): Map
Send content to an open session URI, starting at byte 0 (or
opts.offset), in opts.chunk-size chunks (rounded down to 256 KiB
multiples; default 8 MiB), following the offset Drive reports after
each one. Returns the created/updated file resource.
Example
bytes Bytes("report contents")
session ::google::drive::upload/start-resumable-upload({name: "report.bin"}, "application/octet-stream", length(bytes))
file ::google::drive::upload/upload-resumable(session, bytes, {chunk-size: 524288})
file.id
upload-status
fn (session-uri: Str, total: Int): Map
fn (session-uri: Str, total: Int, opts: Map): Map
Ask Drive how much of a total-byte resumable upload it has stored
(an empty PUT with Content-Range: bytes */total). Returns
{complete, next-offset, file}: next-offset is the next byte to
send (from the 308's Range header; 0 when nothing is stored), and
file is the file resource once complete. An expired session or a
failed query is an Err (::google::api/is-retryable says whether to
try again later).
bytes Bytes("report contents")
session-uri ::google::drive::upload/start-resumable-upload({name: "report.bin"}, "application/octet-stream", length(bytes))
status ::google::drive::upload/upload-status(session-uri, length(bytes))
status.next-offset