This is a GAS library for creating and requesting the type of multipart/form-data using Google Apps Script. This library enhances Class UelFetchApp of Google Apps Script.
This is a Google Apps Script library which enhances Class UrlFetchApp to assist in creating and requesting multipart/form-data.
Google Apps Script provides Class UrlFetchApp with a fetch method fetch(url, params)
, however, the request body for multipart/form-data, must be created by the user, and it is a bit difficult to do so. I've created this library in the hope that simplification of this process would be useful for others.
Method | Description |
---|---|
fetch(url, params) | This method is used for running a single request. This method uses UrlFetchApp.fetch() . The type of "url" and "params" are string and object, respectively. "params" uses the object of UrlFetchApp.fetch(url, params) . In this method, a property of body is added. This is demonstrated in the sample script below. |
fetchAll(requests[]) | This method is used for running multiple requests. This method uses UrlFetchApp.fetchAll() . Each request is processed asynchronously. The type of "requests" is an object. "requests" uses the object of UrlFetchApp.fetchAll(requests) . In this method, a property of body is added. This is demonstrated in the sample script below. |
createFormData() | This method is used for creating an instance of formData. |
append(key, value) | This method appends a formData using key and value to created formData. The type of "key" and "value" are string and blob, respectively. This is demonstrated in the sample script below. |
params
ofFetchApp.fetch(url, params)
andrequests[]
ofFetchApp.fetchAll(requests[])
are basically the same withparams
ofUrlFetchApp.fetch(url, params)
andrequests[]
ofUrlFetchApp.fetchAll(requests[])
, respectively. AtFetchApp
, the property ofbody
is used for giving the form data. Other properties are the same as inUrlFetchApp
.
- If
payload
of property is used inparams
andrequests[]
,body
is not used; it is completely the same as the defaultUrlFetchApp
. Only whenbody
is used is multipart/form-data requested.
I would like to add more methods in the future.
1sm9V-w8-0i3U4-10N6XyaRjHk5voiuJ1ArKSLo3htOUasB6GcPcIq8Kb
1sm9V-w8-0i3U4-10N6XyaRjHk5voiuJ1ArKSLo3htOUasB6GcPcIq8Kb
.FetchApp
". This is set under the default.You can read more about libraries in Apps Script here.
This library uses the following scope. This is installed in the library, and nothing further is required from the user.
https://www.googleapis.com/auth/script.external_request
This method is used for running a single request. This method uses UrlFetchApp.fetch()
. The type of "url" and "params" are string and object, respectively. "params" uses the object of UrlFetchApp.fetch(url, params)
. In this method, a property of body
is added.
As an example, this is how one may convert a PDF file to a new Google Document using the method of files.create. (Drive API v3)
function sample1() {
var fileId = "### fileId of PDF ###";
var metadata = {
name: "sampleDocument", // Filename of created Google Document
mimeType: MimeType.GOOGLE_DOCS, // MimeType of Google Document
};
var fileBlob = DriveApp.getFileById(fileId).getBlob();
var form = FetchApp.createFormData(); // Create form data
form.append(
"metadata",
Utilities.newBlob(JSON.stringify(metadata), "application/json")
);
form.append("file", fileBlob);
var url =
"https://www.googleapis.com/upload/drive/v3/files?uploadType=multipart";
var params = {
method: "POST",
headers: { Authorization: "Bearer " + ScriptApp.getOAuthToken() },
body: form,
};
var res = FetchApp.fetch(url, params);
Logger.log(res);
// DriveApp.createFile(blob) // This comment line is used for automatically detecting scope for running this sample script.
}
At the following sample script, blob
is sent as files
.
function multipartformdata_files() {
var url = "###";
var blob = Utilities.newBlob("sample value", MimeType.PLAIN_TEXT, "sample.txt");
var form = FetchApp.createFormData();
form.append("sample", blob);
var params = {
method: "POST",
headers: { Authorization: "Bearer sampleToken"},
body: form,
};
var res = FetchApp.fetch(url, params);
console.log(res.getContentText());
}
Above script is the same with the following curl command.
$ curl -X POST \
-F sample='@sample.txt;type=text/plain' \
-H 'Content-Type: multipart/form-data' \
'### URL ###'
This method is used for running multiple requests. This method uses UrlFetchApp.fetchAll()
. Each request is processed asynchronously. The type of "requests" is an object. "requests" uses the object of UrlFetchApp.fetchAll(requests)
. In this method, a property of body
is added.
As an example, this shows how to overwrite two existing Google Documents using the content of two text files using the method of files.update. (Drive API v3) Currently, the Drive API batch request cannot use the file media. This sample script might become a workaround for updating files by quasi-batching requests via an asynchronous process.
function sample2() {
var contents = [
{
fileName: "newFilename1", // new filename
docs: "### GoogleDocumentId1 ###", // Destination fileId of existing Google Document.
textFile: "### textFileId1 ###", // Source fileId of text file.
},
{
fileName: "newFilename2",
docs: "### GoogleDocumentId2 ###",
textFile: "### textFileId2 ###",
},
];
var accessToken = ScriptApp.getOAuthToken();
var requests = contents.map(function (e) {
var metadata = { name: e.fileName };
var form = FetchApp.createFormData(); // Create form data
form.append(
"metadata",
Utilities.newBlob(JSON.stringify(metadata), "application/json")
);
form.append("file", DriveApp.getFileById(e.textFile).getBlob());
var url =
"https://www.googleapis.com/upload/drive/v3/files/" +
e.docs +
"?uploadType=multipart";
params = {
url: url,
method: "PATCH",
headers: { Authorization: "Bearer " + accessToken },
body: form,
};
return params;
});
var res = FetchApp.fetchAll(requests);
Logger.log(res);
// DriveApp.createFile(blob) // This comment line is used for automatically detecting scope for running this sample script.
}
createFormData()
and append(key, value)
are used for creating an instance of formData, and appending an object to formData, respectively.
Sample scripts may be seen under the sections for fetch(url, params)
and fetchAll(requests)
.
FormData()
and fetch()
methods in creating these methods.I created this library for requesting multipart/form-data using Google Apps Script. While in my test scenarios, I could confirm that this script works, I am sorry to say that I cannot guarantee it will work for all purposes. I would like to make this library more encompassing; please report any issues you encounter.
I sincerely hope this library is useful for you.
If you have any questions or comments, feel free to contact me.
v1.0.0 (April 20, 2019)
v1.0.1 (April 13, 2020)
v1.0.2 (September 19, 2020)
files
.