Google Apps Script

Class Utilities

This service provides utilities for string encoding/decoding, date formatting, JSON manipulation, and other miscellaneous tasks.

Properties

PropertyTypeDescription
CharsetCharset
DigestAlgorithmDigestAlgorithm
MacAlgorithmMacAlgorithm

Methods

MethodReturn typeBrief description
base64Decode(encoded)Byte[]Decodes a base 64 encoded string as a byte array.
base64Decode(encoded, charset)Byte[]Decodes a base 64 encoded string as a byte array.
base64Encode(data)StringGiven an array of bytes, returns the data as a base 64 encoded string.
base64Encode(data)StringGiven string, returns the data as a base 64 encoded string.
base64Encode(data, charset)StringGiven a string with a specific Charset, returns the data as a base 64 encoded string.
computeDigest(algorithm, value)Byte[]Compute a digest using the specified algorithm on the specified value
computeDigest(algorithm, value, charset)Byte[]Compute a digest using the specified algorithm on the specified value
computeHmacSha256Signature(value, key)Byte[]Signs the provided value using HMAC-SHA256 with the given key.
computeHmacSha256Signature(value, key, charset)Byte[]Signs the provided value using HMAC-SHA256 with the given key and character set.
computeHmacSignature(algorithm, value, key)Byte[]Compute a message authentication code using the specified algorithm on the specified key and value.
computeHmacSignature(algorithm, value, key, charset)Byte[]Compute a message authentication code using the specified algorithm on the specified key and value.
formatDate(date, timeZone, format)StringFormats date according to specification described in Java SE SimpleDateFormat class.
formatString(template, args)StringPerforms sprintf-like string formatting using '%'-style format strings.
newBlob(data)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
newBlob(data, contentType)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
newBlob(data, contentType, name)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
newBlob(data)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
newBlob(data, contentType)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
newBlob(data, contentType, name)BlobCreate a new Blob object that is used in many Apps Script APIs that take binary data as input.
parseCsv(csv)String[][]Returns a tabular 2D array representation of a CSV string.
parseCsv(csv, delimiter)String[][]Returns a tabular 2D array representation of a CSV string using a custom delimiter.
sleep(milliseconds)voidSleeps for specified number of milliseconds.
unzip(blob)Blob[]Takes a Blob representing a zip file and returns its component files.
zip(blobs)BlobCreates a new Blob object that is a zip file containing the data from the Blobs passed in.
zip(blobs, name)BlobCreates a new Blob object that is a zip file containing the data from the Blobs passed in.

Detailed documentation

base64Decode(encoded)

Decodes a base 64 encoded string as a byte array. Decodes to UTF-8 as the default.

 
// This is the base64 encoded form of "Google グループ"
 var base64data = "R29vZ2xlIOOCsOODq+ODvOODlw==";

 var decoded = Utilities.base64Decode(base64data);

 // This will log:
 //     [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
 //      -29, -125, -85, -29, -125, -68, -29, -125, -105]
 Logger.log(decoded);

 // If we want a String instead of a byte[]:
 // This will log the original "Google グループ"
 Logger.log(Utilities.newBlob(decoded).getDataAsString());
 

Parameters

NameTypeDescription
encodedStringa byte[] of data to decode

Return

Byte[] — the raw data represented by the base-64 encoded argument as a byte[]


base64Decode(encoded, charset)

Decodes a base 64 encoded string as a byte array.

 
// This is the base64 encoded form of "Google グループ"
 var base64data = "R29vZ2xlIOOCsOODq+ODvOODlw==";

 var decoded = Utilities.base64Decode(base64data, Utilities.Charset.UTF_8);

 // This will log:
 //     [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
 //      -29, -125, -85, -29, -125, -68, -29, -125, -105]
 Logger.log(decoded);

 // If we want a String instead of a byte[]:
 // This will log the original "Google グループ"
 Logger.log(Utilities.newBlob(decoded).getDataAsString());
 

Parameters

NameTypeDescription
encodedStringa String of data to decode
charsetCharseta Charset specifying the charset of the input

Return

Byte[] — the raw data represented by the base-64 encoded argument as a byte[]


base64Encode(data)

Given an array of bytes, returns the data as a base 64 encoded string. Base 64 is a common encoding accepted by a variety of tools that cannot accept binary data. Base 64 is commonly used in internet protocols such as email, HTTP, or in XML documents.

 
// We'll instantiate a blob here for clarity
 var blob = Utilities.newBlob("A string here");

 // Let's return the blob data as a byte[]
 var encoded = Utilities.base64Encode(blob.getBytes());

 // This will write 'QSBzdHJpbmcgaGVyZQ==' to the log.
 Logger.log(encoded);
 

Parameters

NameTypeDescription
dataByte[]a byte[] of data to encode

Return

String — the base 64 encoded representation of the passed in data


base64Encode(data)

Given string, returns the data as a base 64 encoded string. Base 64 is a common encoding accepted by a variety of tools that cannot accept binary data. Base 64 is commonly used in internet protocols such as email, HTTP, or in XML documents.

 
// Let's return the blob data as a byte[]
 var encoded = Utilities.base64Encode("A string here");

 // This will write 'QSBzdHJpbmcgaGVyZQ==' to the log.
 Logger.log(encoded);
 

Parameters

NameTypeDescription
dataStringA String to encode

Return

String — the base 64 encoded representation of the input string


base64Encode(data, charset)

Given a string with a specific Charset, returns the data as a base 64 encoded string. A Charset is a way of encoding characters such that they can be encoded. These are typically done in a binary format, which can generally be incompatible with certain data transmission protocols. To make the data compatible, they are generally encoded into base 64, which is a common encoding accepted by a variety of tools that cannot accept binary data. Base 64 is commonly used in internet protocols such as email, HTTP, or in XML documents.

 
// "Google Groups" in Katakana (Japanese)
 var input = "Google グループ";

 // Writes "R29vZ2xlIOOCsOODq+ODvOODlw==" to the log
 var encoded = Utilities.base64Encode(input, Utilities.Charset.UTF_8);
 Logger.log(encoded);

 

Parameters

NameTypeDescription
dataStringa String of data to encode
charsetCharseta Charset specifying the charset of the input

Return

String — the base 64 encoded representation of the input string with the given Charset


computeDigest(algorithm, value)

Compute a digest using the specified algorithm on the specified value

 
var digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5, "input to hash");
 Logger.log(digest);
 

Parameters

NameTypeDescription
algorithmDigestAlgorithma DigestAlgorithm to use
valueStringan input string value to compute a digest for

Return

Byte[] — a byte[] representing the output digest


computeDigest(algorithm, value, charset)

Compute a digest using the specified algorithm on the specified value

 
var digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5,
                                      "input to hash",
                                      Utilities.Charset.US_ASCII);
 Logger.log(digest);
 

Parameters

NameTypeDescription
algorithmDigestAlgorithma DigestAlgorithm to use
valueStringan input string value to compute a digest for
charsetCharseta Charset representing the input character set

Return

Byte[] — a byte[] representing the output digest


computeHmacSha256Signature(value, key)

Signs the provided value using HMAC-SHA256 with the given key.

 
// This will write an array of bytes to the log.
 var signature = Utilities.computeHmacSha256Signature("this is my input",
                                                       "my key - use a stronger one");
 Logger.log(signature);
 

Parameters

NameTypeDescription
valueStringthe input value to generate a hash for
keyStringa key to use to generate the hash with

Return

Byte[] — a byte[] representing the output signature


computeHmacSha256Signature(value, key, charset)

Signs the provided value using HMAC-SHA256 with the given key and character set.

 
// This will write an array of bytes to the log.
 var signature = Utilities.computeHmacSha256Signature("this is my input",
                                                      "my key - use a stronger one",
                                                      Utilities.Charset.US_ASCII);
 Logger.log(signature);
 

Parameters

NameTypeDescription
valueStringthe input value to generate a hash for
keyStringa key to use to generate the hash with
charsetCharseta Charset representing the input character set

Return

Byte[] — a byte[] representing the output signature


computeHmacSignature(algorithm, value, key)

Compute a message authentication code using the specified algorithm on the specified key and value.

 
// This will write an array of bytes to the log.
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_MD5,
                                                "input to hash",
                                                "key");
 Logger.log(signature);
 

Parameters

NameTypeDescription
algorithmMacAlgorithma MacAlgorithm algorithm to use to hash the input value
valueStringthe input value to generate a hash for
keyStringa key to use to generate the hash with

Return

Byte[] — a byte[] representing the output signature


computeHmacSignature(algorithm, value, key, charset)

Compute a message authentication code using the specified algorithm on the specified key and value.

 
// This will write an array of bytes to the log.
 var signature = Utilities.computeHmacSignature(Utilities.MacAlgorithm.HMAC_MD5,
                                                "input to hash",
                                                "key",
                                                Utilities.Charset.US_ASCII);
 Logger.log(signature);
 

Parameters

NameTypeDescription
algorithmMacAlgorithma MacAlgorithm algorithm to use to hash the input value
valueStringthe input value to generate a hash for
keyStringa key to use to generate the hash with
charsetCharseta Charset representing the input character set

Return

Byte[] — a byte[] representing the output signature


formatDate(date, timeZone, format)

Formats date according to specification described in Java SE SimpleDateFormat class. Please visit the specification at http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html

 
// This formats the date as Greenwich Mean Time in the format
 // year-month-dateThour-minute-second.
 var formattedDate = Utilities.formatDate(new Date(), "GMT", "yyyy-MM-dd'T'HH:mm:ss'Z'");
 Logger.log(formattedDate);
 

Parameters

NameTypeDescription
dateDatea Date to format as a String
timeZoneStringthe output timezone of the result
formatStringa format per the java.text.SimpleDateFormat specification

Return

String — the input date as a formatted string


formatString(template, args)

Performs sprintf-like string formatting using '%'-style format strings.

 
// will be: "123.456000"
 Utilities.formatString('%11.6f', 123.456);

 // will be: "   abc"
 Utilities.formatString('%6s', 'abc');
 

Parameters

NameTypeDescription
templateStringThe format string that controls what gets returned.
argsObject...Objects to use to fill in the '%' placeholders in the template.

Return

String — the formatted string.


newBlob(data)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataByte[]the bytes for the blob

Return

Blob — the newly created Blob


newBlob(data, contentType)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataByte[]the bytes for the blob
contentTypeStringthe content type of the blob - can be null

Return

Blob — the newly created Blob


newBlob(data, contentType, name)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataByte[]the bytes for the blob
contentTypeString- the content type of the blob - can be null
nameStringthe name of the blob - can be null

Return

Blob — the newly created Blob


newBlob(data)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataStringthe string for the blob, assumed UTF-8

Return

Blob — the newly created Blob


newBlob(data, contentType)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataStringthe string for the blob, assumed UTF-8
contentTypeStringthe content type of the blob - can be null

Return

Blob — the newly created Blob


newBlob(data, contentType, name)

Create a new Blob object that is used in many Apps Script APIs that take binary data as input.

Parameters

NameTypeDescription
dataStringthe string for the blob, assumed UTF-8
contentTypeStringthe content type of the blob - can be null
nameStringthe name of the blob - can be null

Return

Blob — the newly created Blob


parseCsv(csv)

Returns a tabular 2D array representation of a CSV string.

 
// This will create a 2 dimensional array of the format [[a, b, c], [d, e, f]]
 var csvString = "a,b,c\nd,e,f";
 var data = Utilities.parseCsv(csvString);
 

Parameters

NameTypeDescription
csvStringa string containing a single or multiline data in comma-separated value (CSV) format

Return

String[][] — a 2 dimensional array containing the values in the CSV string


parseCsv(csv, delimiter)

Returns a tabular 2D array representation of a CSV string using a custom delimiter.

 
// This will create a 2 dimensional array of the format [[a, b, c], [d, e, f]]
 var csvString = "a,b,c\td,e,f";
 var data = Utilities.parseCsv(csvString, '\t');
 

Parameters

NameTypeDescription
csvStringa string containing a single or multiline data in comma-separated value (CSV) format
delimiterCharbetween values

Return

String[][] — a 2 dimensional array containing the values in the CSV string


sleep(milliseconds)

Sleeps for specified number of milliseconds. Immediately puts the script to sleep for the specified number of milliseconds. The maximum allowed value is 300000 (or 5 minutes).

Parameters

NameTypeDescription
millisecondsIntegerThe number of milliseconds to sleep.

unzip(blob)

Takes a Blob representing a zip file and returns its component files.

 
var googleFavIconUrl = "https://www.google.com/favicon.ico";
 var googleLogoUrl = "https://www.google.com/images/srpr/logo3w.png";

 // Fetch the Google favicon.ico file and get the Blob data
 var faviconBlob = UrlFetchApp.fetch(googleFavIconUrl).getBlob();
 var logoBlob = UrlFetchApp.fetch(googleLogoUrl).getBlob();

 // zip now references a blob containing an archive of both faviconBlob and logoBlob
 var zip = Utilities.zip([faviconBlob, logoBlob], "google_images.zip");

 // This will now unzip the blobs
 var files = Utilities.unzip(zip);
 

Parameters

NameTypeDescription
blobBlobSourcethe zip file blob.

Return

Blob[] — a Blob[] representing the component blobs, each named with the full path inside the zip


zip(blobs)

Creates a new Blob object that is a zip file containing the data from the Blobs passed in.

 
var googleFavIconUrl = "https://www.google.com/favicon.ico";
 var googleLogoUrl = "https://www.google.com/images/srpr/logo3w.png";

 // Fetch the Google favicon.ico file and get the Blob data
 var faviconBlob = UrlFetchApp.fetch(googleFavIconUrl).getBlob();
 var logoBlob = UrlFetchApp.fetch(googleLogoUrl).getBlob();

 // zip now references a blob containing an archive of both faviconBlob and logoBlob
 var zip = Utilities.zip([faviconBlob, logoBlob]);
 

Parameters

NameTypeDescription
blobsBlobSource[]a array of blobs to zip up

Return

Blob — a new blob containing the inputs as an archive


zip(blobs, name)

Creates a new Blob object that is a zip file containing the data from the Blobs passed in. This version of the method allows a filename to be specified.

 
var googleFavIconUrl = "https://www.google.com/favicon.ico";
 var googleLogoUrl = "https://www.google.com/images/srpr/logo3w.png";

 // Fetch the Google favicon.ico file and get the Blob data
 var faviconBlob = UrlFetchApp.fetch(googleFavIconUrl).getBlob();
 var logoBlob = UrlFetchApp.fetch(googleLogoUrl).getBlob();

 // zip now references a blob containing an archive of both faviconBlob and logoBlob
 var zip = Utilities.zip([faviconBlob, logoBlob], "google_images.zip");
 

Parameters

NameTypeDescription
blobsBlobSource[]a array of blobs to zip up
nameStringthe name of the zip file to be created

Return

Blob — a new blob containing the inputs as an archive

Deprecated methods


Authentification requise

Vous devez être connecté à Google+ pour effectuer cette opération.

Connexion en cours…

Le site Google pour les développeurs a besoin de votre autorisation pour effectuer cette opération.