Utilities

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

### Properties

| Property | Type | Description |
|---|---|---|
| `Charset` | `https://developers.google.com/apps-script/reference/utilities/charset` |   |
| `DigestAlgorithm` | `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` |   |
| `MacAlgorithm` | `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` |   |
| `RsaAlgorithm` | `https://developers.google.com/apps-script/reference/utilities/rsa-algorithm` |   |

### Methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64Decode(String)` | `Byte[]` | Decodes a base-64 encoded string into a UTF-8 byte array. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64Decode(String,Charset)` | `Byte[]` | Decodes a base-64 encoded string into a byte array in a specific character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64DecodeWebSafe(String)` | `Byte[]` | Decodes a base-64 web-safe encoded string into a UTF-8 byte array. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64DecodeWebSafe(String,Charset)` | `Byte[]` | Decodes a base-64 web-safe encoded string into a byte array in a specific character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64Encode(Byte)` | `String` | Generates a base-64 encoded string from the given byte array. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64Encode(String)` | `String` | Generates a base-64 encoded string from the given string. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64Encode(String,Charset)` | `String` | Generates a base-64 encoded string from the given string in a specific character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64EncodeWebSafe(Byte)` | `String` | Generates a base-64 web-safe encoded string from the given byte array. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64EncodeWebSafe(String)` | `String` | Generates a base-64 web-safe encoded string from the given string. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#base64EncodeWebSafe(String,Charset)` | `String` | Generates a base-64 web-safe encoded string from the given string in a specific character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeDigest(DigestAlgorithm,Byte)` | `Byte[]` | Compute a digest using the specified algorithm on the specified `Byte[]` value. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeDigest(DigestAlgorithm,String)` | `Byte[]` | Compute a digest using the specified algorithm on the specified `String` value. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeDigest(DigestAlgorithm,String,Charset)` | `Byte[]` | Compute a digest using the specified algorithm on the specified `String` value with the given character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSha256Signature(Byte,Byte)` | `Byte[]` | Signs the provided value using HMAC-SHA256 with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSha256Signature(String,String)` | `Byte[]` | Signs the provided value using HMAC-SHA256 with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSha256Signature(String,String,Charset)` | `Byte[]` | Signs the provided value using HMAC-SHA256 with the given key and character set. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSignature(MacAlgorithm,Byte,Byte)` | `Byte[]` | Compute a message authentication code using the specified algorithm on the specified key and value. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSignature(MacAlgorithm,String,String)` | `Byte[]` | Compute a message authentication code using the specified algorithm on the specified key and value. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeHmacSignature(MacAlgorithm,String,String,Charset)` | `Byte[]` | Compute a message authentication code using the specified algorithm on the specified key and value. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSha1Signature(String,String)` | `Byte[]` | Signs the provided value using RSA-SHA1 with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSha1Signature(String,String,Charset)` | `Byte[]` | Signs the provided value using RSA-SHA1 with the given key and charset. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSha256Signature(String,String)` | `Byte[]` | Signs the provided value using RSA-SHA256 with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSha256Signature(String,String,Charset)` | `Byte[]` | Signs the provided value using RSA-SHA256 with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSignature(RsaAlgorithm,String,String)` | `Byte[]` | Signs the provided value using the specified RSA algorithm with the given key. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#computeRsaSignature(RsaAlgorithm,String,String,Charset)` | `Byte[]` | Signs the provided value using the specified RSA algorithm with the given key and charset. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#formatDate(Date,String,String)` | `String` | Formats date according to specification described in Java SE SimpleDateFormat class. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#formatString(String,Object...)` | `String` | Performs `sprintf`-like string formatting using '%'-style format strings. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#getUuid()` | `String` | Get a UUID as a string (equivalent to using the [`java.util.UUID.randomUUID()`](https://docs.oracle.com/javase/7/docs/api/java/util/UUID.html) method). |
| `https://developers.google.com/apps-script/reference/utilities/utilities#gzip(BlobSource)` | `https://developers.google.com/apps-script/reference/base/blob.html` | `gzip`-compresses the provided `https://developers.google.com/apps-script/reference/base/blob.html` data and returns it in a new `https://developers.google.com/apps-script/reference/base/blob.html` object. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#gzip(BlobSource,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | `gzip`-compresses the provided `https://developers.google.com/apps-script/reference/base/blob.html` data and returns it in a new `https://developers.google.com/apps-script/reference/base/blob.html` object. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(Byte)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a byte array. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(Byte,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a byte array and content type. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(Byte,String,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a byte array, content type, and name. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a string. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(String,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a string and content type. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#newBlob(String,String,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Create a new Blob object from a string, content type, and name. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#parseCsv(String)` | `String[][]` | Returns a tabular 2D array representation of a CSV string. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#parseCsv(String,Char)` | `String[][]` | Returns a tabular 2D array representation of a CSV string using a custom delimiter. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#parseDate(String,String,String)` | `Date` | Parses the provided string date according to the specification described in the Java Standard Edition `SimpleDateFormat` class. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#sleep(Integer)` | `void` | Sleeps for specified number of milliseconds. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#ungzip(BlobSource)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Uncompresses a `https://developers.google.com/apps-script/reference/base/blob.html` object and returns a `https://developers.google.com/apps-script/reference/base/blob.html` containing the uncompressed data. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#unzip(BlobSource)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Takes a Blob representing a zip file and returns its component files. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#zip(BlobSource)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Creates a new Blob object that is a zip file containing the data from the Blobs passed in. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#zip(BlobSource,String)` | `https://developers.google.com/apps-script/reference/base/blob.html` | Creates a new Blob object that is a zip file containing the data from the Blobs passed in. |

### Deprecated methods

| Method | Return type | Brief description |
|---|---|---|
| `https://developers.google.com/apps-script/reference/utilities/utilities#jsonParse(String)` | `Object` | Return an object corresponding to the JSON string passed in. |
| `https://developers.google.com/apps-script/reference/utilities/utilities#jsonStringify(Object)` | `String` | Return a JSON string of the object passed in. |

## Detailed documentation

### `base64Decode(encoded)`

Decodes a base-64 encoded string into a UTF-8 byte array.

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

// This logs:
//     [71, 111, 111, 103, 108, 101, 32, -29, -126, -80,
//      -29, -125, -85, -29, -125, -68, -29, -125, -105]
const decoded = Utilities.base64Decode(base64data);
Logger.log(decoded);

// If you want a String instead of a byte array:
// This logs the original "Google グループ"
Logger.log(Utilities.newBlob(decoded).getDataAsString());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `encoded` | `String` | An array of bytes of data to decode. |

#### Return


`Byte[]` --- The raw data represented by the base-64 encoded argument as a byte array.

*** ** * ** ***

### `base64Decode(encoded, charset)`

Decodes a base-64 encoded string into a byte array in a specific character set.

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

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

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

// If you want a String instead of a byte array:
// This logs the original "Google グループ"
Logger.log(Utilities.newBlob(decoded).getDataAsString());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `encoded` | `String` | The string of data to decode. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/charset` specifying the charset of the input. |

#### Return


`Byte[]` --- The raw data represented by the base-64 encoded argument as a byte array.

*** ** * ** ***

### `base64DecodeWebSafe(encoded)`

Decodes a base-64 web-safe encoded string into a UTF-8 byte array.

```javascript
// This is the base64 web-safe encoded form of "Google グループ"
const base64data = 'R29vZ2xlIOOCsOODq-ODvOODlw==';

const decoded = Utilities.base64DecodeWebSafe(base64data);

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

// If you want a String instead of a byte array:
// This logs the original "Google グループ"
Logger.log(Utilities.newBlob(decoded).getDataAsString());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `encoded` | `String` | An array of bytes of web-safe data to decode. |

#### Return


`Byte[]` --- The raw data represented by the base-64 web-safe encoded argument as a byte array.

*** ** * ** ***

### `base64DecodeWebSafe(encoded, charset)`

Decodes a base-64 web-safe encoded string into a byte array in a specific character set.

```javascript
// This is the base64 web-safe encoded form of "Google グループ"
const base64data = 'R29vZ2xlIOOCsOODq-ODvOODlw==';

const decoded = Utilities.base64DecodeWebSafe(
    base64data,
    Utilities.Charset.UTF_8,
);

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

// If you want a String instead of a byte array:
// This logs the original "Google グループ"
Logger.log(Utilities.newBlob(decoded).getDataAsString());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `encoded` | `String` | The string of web-safe data to decode. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/charset` specifying the charset of the input. |

#### Return


`Byte[]` --- The raw data represented by the base-64 web-safe encoded argument as a byte array.

*** ** * ** ***

### `base64Encode(data)`

Generates a base-64 encoded string from the given byte array. 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.

```javascript
// Instantiates a blob here for clarity
const blob = Utilities.newBlob('A string here');

// Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
const encoded = Utilities.base64Encode(blob.getBytes());
Logger.log(encoded);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `Byte[]` | A byte\[\] of data to encode. |

#### Return


`String` --- The base-64 encoded representation of the passed in data.

*** ** * ** ***

### `base64Encode(data)`

Generates a base-64 encoded string from the given 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.

```javascript
// Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
const encoded = Utilities.base64Encode('A string here');
Logger.log(encoded);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string to encode. |

#### Return


`String` --- The base-64 encoded representation of the input string.

*** ** * ** ***

### `base64Encode(data, charset)`

Generates a base-64 encoded string from the given string in a specific character set. 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.

```javascript
// "Google Groups" in Katakana (Japanese)
const input = 'Google グループ';

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

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string of data to encode. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `Charset` specifying the charset of the input. |

#### Return


`String` --- The base-64 encoded representation of the input string with the given `Charset`.

*** ** * ** ***

### `base64EncodeWebSafe(data)`

Generates a base-64 web-safe encoded string from the given byte array. Base 64 is a common
encoding accepted by a variety of tools that cannot accept binary data. Base 64 web-safe is
commonly used in internet protocols such as email, HTTP, or in XML documents.

```javascript
// Instantiates a blob here for clarity
const blob = Utilities.newBlob('A string here');

// Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
const encoded = Utilities.base64EncodeWebSafe(blob.getBytes());
Logger.log(encoded);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `Byte[]` | An array of bytes of data to encode. |

#### Return


`String` --- The base-64 web-safe encoded representation of the passed in data.

*** ** * ** ***

### `base64EncodeWebSafe(data)`

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

```javascript
// Writes 'QSBzdHJpbmcgaGVyZQ==' to the log.
const encoded = Utilities.base64EncodeWebSafe('A string here');
Logger.log(encoded);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string to encode. |

#### Return


`String` --- The base-64 web-safe encoded representation of the input string.

*** ** * ** ***

### `base64EncodeWebSafe(data, charset)`

Generates a base-64 web-safe encoded string from the given string in a specific character set.
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 web-safe
is commonly used in internet protocols such as email, HTTP, or in XML documents.

```javascript
// "Google Groups" in Katakana (Japanese)
const input = 'Google グループ';

// Writes "R29vZ2xlIOOCsOODq-ODvOODlw==" to the log
const encoded = Utilities.base64EncodeWebSafe(input, Utilities.Charset.UTF_8);
Logger.log(encoded);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string of data to encode. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `Charset` specifying the charset of the input. |

#### Return


`String` --- The base-64 web-safe encoded representation of the input string with the given `Charset`.

*** ** * ** ***

### `computeDigest(algorithm, value)`

Compute a digest using the specified algorithm on the specified `Byte[]` value.

```javascript
const input = Utilities.base64Decode(
    'aW5wdXQgdG8gaGFzaA0K');  // == base64encode("input to hash")
const digest = Utilities.computeDigest(Utilities.DigestAlgorithm.MD5, input);
Logger.log(digest);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` to use. |
| `value` | `Byte[]` | An input string value to compute a digest for. |

#### Return


`Byte[]` --- A byte\[\] representing the output digest.

*** ** * ** ***

### `computeDigest(algorithm, value)`

Compute a digest using the specified algorithm on the specified `String` value.

```javascript
const digest = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    'input to hash',
);
Logger.log(digest);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` to use. |
| `value` | `String` | An 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 `String` value with the
given character set.

```javascript
const digest = Utilities.computeDigest(
    Utilities.DigestAlgorithm.MD5,
    'input to hash',
    Utilities.Charset.US_ASCII,
);
Logger.log(digest);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/digest-algorithm` to use. |
| `value` | `String` | An input string value to compute a digest for. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/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.

```javascript
// This writes an array of bytes to the log.
const input = Utilities.base64Decode(
    'aW5wdXQgdG8gaGFzaA0K');                 // == base64encode("input to hash")
const key = Utilities.base64Decode('a2V5');  // == base64encode("key")
const signature = Utilities.computeHmacSha256Signature(input, key);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `Byte[]` | The input value to generate a hash for. |
| `key` | `Byte[]` | A key to use to generate the hash with. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeHmacSha256Signature(value, key)`

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

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeHmacSha256Signature(
    'this is my input',
    'my key - use a stronger one',
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A 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.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeHmacSha256Signature(
    'this is my input',
    'my key - use a stronger one',
    Utilities.Charset.US_ASCII,
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A key to use to generate the hash with. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/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.

```javascript
// This writes an array of bytes to the log.
const input = Utilities.base64Decode(
    'aW5wdXQgdG8gaGFzaA0K');                 // == base64encode("input to hash")
const key = Utilities.base64Decode('a2V5');  // == base64encode("key")
const signature = Utilities.computeHmacSignature(
    Utilities.MacAlgorithm.HMAC_MD5,
    input,
    key,
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` algorithm to use to hash the input value. |
| `value` | `Byte[]` | The input value to generate a hash for. |
| `key` | `Byte[]` | A key to use to generate the hash with. |

#### 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.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeHmacSignature(
    Utilities.MacAlgorithm.HMAC_MD5,
    'input to hash',
    'key',
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` algorithm to use to hash the input value. |
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A 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.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeHmacSignature(
    Utilities.MacAlgorithm.HMAC_MD5,
    'input to hash',
    'key',
    Utilities.Charset.US_ASCII,
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/mac-algorithm` algorithm to use to hash the input value. |
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A key to use to generate the hash with. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/charset` representing the input character set. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSha1Signature(value, key)`

Signs the provided value using RSA-SHA1 with the given key.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSha1Signature(
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSha1Signature(value, key, charset)`

Signs the provided value using RSA-SHA1 with the given key and charset.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSha1Signature(
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
    Utilities.Charset.US_ASCII,
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/charset` representing the input character set. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSha256Signature(value, key)`

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

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSha256Signature(
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSha256Signature(value, key, charset)`

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

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSha256Signature(
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/charset` representing the input character set. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSignature(algorithm, value, key)`

Signs the provided value using the specified RSA algorithm with the given key.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSignature(
    Utilities.RsaAlgorithm.RSA_SHA_256,
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/rsa-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/rsa-algorithm` algorithm to use to hash the input value. |
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |

#### Return


`Byte[]` --- A byte\[\] representing the output signature.

*** ** * ** ***

### `computeRsaSignature(algorithm, value, key, charset)`

Signs the provided value using the specified RSA algorithm with the given key and charset.

```javascript
// This writes an array of bytes to the log.
const signature = Utilities.computeRsaSignature(
    Utilities.RsaAlgorithm.RSA_SHA_256,
    'this is my input',
    PropertiesService.getScriptProperties().getProperty('YOUR_PRIVATE_KEY'),
    Utilities.Charset.US_ASCII,
);
Logger.log(signature);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `algorithm` | `https://developers.google.com/apps-script/reference/utilities/rsa-algorithm` | A `https://developers.google.com/apps-script/reference/utilities/rsa-algorithm` algorithm to use to hash the input value. |
| `value` | `String` | The input value to generate a hash for. |
| `key` | `String` | A PEM formatted key to use to generate the signature. |
| `charset` | `https://developers.google.com/apps-script/reference/utilities/charset` | A `https://developers.google.com/apps-script/reference/utilities/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>


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

#### Parameters

| Name | Type | Description |
|---|---|---|
| `date` | `Date` | A `Date` to format as a String. |
| `timeZone` | `String` | The output timezone of the result. |
| `format` | `String` | A format per the `SimpleDateFormat` specification. |

#### Return


`String` --- The input date as a formatted string.

*** ** * ** ***

### `formatString(template, args)`

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

```javascript
// " 123.456000"
Utilities.formatString('%11.6f', 123.456);

// "   abc"
Utilities.formatString('%6s', 'abc');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `template` | `String` | The format string that controls what gets returned. |
| `args` | `Object...` | Objects to use to fill in the '%' placeholders in the template. |

#### Return


`String` --- The formatted string.

*** ** * ** ***

### `getUuid()`

Get a UUID as a string (equivalent to using the [`java.util.UUID.randomUUID()`](https://docs.oracle.com/javase/7/docs/api/java/util/UUID.html) method). This identifier is not guaranteed to be unique across
all time and space. As such, do not use in situations where guaranteed uniqueness is required.

```javascript
// This assigns a UUID as a temporary ID for a data object you are creating in
// your script.
const myDataObject = {
  tempId: Utilities.getUuid(),
};
```

#### Return


`String` --- A string representation of the UUID.

*** ** * ** ***

### `gzip(blob)`


`gzip`-compresses the provided `https://developers.google.com/apps-script/reference/base/blob.html` data and returns it in a new `https://developers.google.com/apps-script/reference/base/blob.html` object.

```javascript
const textBlob = Utilities.newBlob(
    'Some text to compress using gzip compression',
);

// Create the compressed blob.
const gzipBlob = Utilities.gzip(textBlob);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blob` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | A `https://developers.google.com/apps-script/reference/base/blob.html` object to compress using `gzip`. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- A new `https://developers.google.com/apps-script/reference/base/blob.html` containing the compressed data.

*** ** * ** ***

### `gzip(blob, name)`


`gzip`-compresses the provided `https://developers.google.com/apps-script/reference/base/blob.html` data and returns it in a new `https://developers.google.com/apps-script/reference/base/blob.html` object. This version of the method allows a filename to be specified.

```javascript
const textBlob = Utilities.newBlob(
    'Some text to compress using gzip compression',
);

// Create the compressed blob.
const gzipBlob = Utilities.gzip(textBlob, 'text.gz');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blob` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | A `https://developers.google.com/apps-script/reference/base/blob.html` object to compress using `gzip`. |
| `name` | `String` | The name of the `gzip` file to be created. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- A new `https://developers.google.com/apps-script/reference/base/blob.html` containing the compressed data.

*** ** * ** ***

### `newBlob(data)`

Create a new Blob object from a byte array. Blobs are used in many Apps Script APIs that take
binary data as input.

```javascript
// Creates a blob object from a byte array.
const data = [71, 79, 79, 71, 76, 69];
const blob = Utilities.newBlob(data);

// Logs the blob data as a string to the console.
console.log(blob.getDataAsString());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `Byte[]` | The bytes for the blob. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `newBlob(data, contentType)`

Create a new Blob object from a byte array and content type. Blobs are used in many Apps Script
APIs that take binary data as input.

```javascript
// Declares a byte array.
const data = [71, 79, 79, 71, 76, 69];

// Declares the content type of the blob.
const contentType = 'application/json';

// Creates a blob object from the byte array and content type.
const blob = Utilities.newBlob(data, contentType);

// Logs the blob data as a string to the console.
console.log(blob.getDataAsString());

// Logs the content type of the blob to the console.
console.log(blob.getContentType());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `Byte[]` | The bytes for the blob. |
| `contentType` | `String` | The content type of the blob - can be `null`. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `newBlob(data, contentType, name)`

Create a new Blob object from a byte array, content type, and name. Blobs are used in many Apps
Script APIs that take binary data as input.

```javascript
// Declares a byte array.
const data = [71, 79, 79, 71, 76, 69];

// Declares the content type of the blob.
const contentType = 'application/json';

// Declares the name of the blob.
const name = 'Example blob';

// Creates a blob object from the byte array, content type, and name.
const blob = Utilities.newBlob(data, contentType, name);

// Logs the blob data as a string to the console.
console.log('Blob data:', blob.getDataAsString());

// Logs the content type of the blob to the console.
console.log('Blob content type:', blob.getContentType());

// Logs the name of the blob to the console.
console.log('Blob name:', blob.getName());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `Byte[]` | The bytes for the blob. |
| `contentType` | `String` | - The content type of the blob - can be `null`. |
| `name` | `String` | The name of the blob - can be `null`. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `newBlob(data)`

Create a new Blob object from a string. Blobs are used in many Apps Script APIs that take
binary data as input.

```javascript
// Declares a string for the blob.
const data = 'GOOGLE';

// Creates a blob object from a string.
const blob = Utilities.newBlob(data);

// Logs the blob data in byte array to the console.
console.log('Blob Data:', blob.getBytes());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string for the blob, assumed UTF-8. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `newBlob(data, contentType)`

Create a new Blob object from a string and content type. Blobs are used in many Apps Script
APIs that take binary data as input.

```javascript
// Declares a string for the blob.
const data = 'GOOGLE';

// Declares the content type of blob.
const contentType = 'application/json';

// Creates a blob object from the string and content type.
const blob = Utilities.newBlob(data, contentType);

// Logs the blob data in byte array to the console.
console.log('Blob data:', blob.getBytes());

// Logs the content type of the blob to the console.
console.log(blob.getContentType());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string for the blob, assumed UTF-8. |
| `contentType` | `String` | The content type of the blob - can be `null`. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `newBlob(data, contentType, name)`

Create a new Blob object from a string, content type, and name. Blobs are used in many Apps
Script APIs that take binary data as input.

```javascript
// Declares a string for the blob.
const data = 'GOOGLE';

// Declares the content type of the blob.
const contentType = 'application/json';

// Declares the name of the blob.
const name = 'Example blob';

// Create a blob object from the string, content type, and name.
const blob = Utilities.newBlob(data, contentType, name);

// Logs the blob data in byte array to the console.
console.log('Blob data:', blob.getBytes());

// Logs the content type of the blob to the console.
console.log('Blob content type:', blob.getContentType());

// Logs the name of the blob to the console.
console.log('Blob name:', blob.getName());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `data` | `String` | The string for the blob, assumed UTF-8. |
| `contentType` | `String` | The content type of the blob - can be `null`. |
| `name` | `String` | The name of the blob - can be `null`. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- The newly created Blob.

*** ** * ** ***

### `parseCsv(csv)`

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

```javascript
// This creates a two-dimensional array of the format [[a, b, c], [d, e, f]]
const csvString = 'a,b,c\nd,e,f';
const data = Utilities.parseCsv(csvString);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `csv` | `String` | A string containing a single or multiline data in comma-separated value (CSV) format. |

#### Return


`String[][]` --- A two-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.

```javascript
// This creates a two-dimensional array of the format [[a, b, c], [d, e, f]]
const csvString = 'a\tb\tc\nd\te\tf';
const data = Utilities.parseCsv(csvString, '\t');
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `csv` | `String` | A string containing a single or multiline data in comma-separated value (CSV) format. |
| `delimiter` | `Char` | Between values. |

#### Return


`String[][]` --- A two-dimensional array containing the values in the CSV string.

*** ** * ** ***

### `parseDate(date, timeZone, format)`

Parses the provided string date according to the specification described in the Java Standard
Edition `SimpleDateFormat` class. For more information, see the Java [`SimpleDateFormat` class](http://docs.oracle.com/javase/7/docs/api/java/text/SimpleDateFormat.html).

```javascript
// This set of parameters parses the given string as a date in Greenwich Mean
// Time, formatted as year-month-dateThour-minute-second.
const date = Utilities.parseDate(
    '1970-01-01 00:00:00',
    'GMT',
    'yyyy-MM-dd\' \'HH:mm:ss',
);
Logger.log(date);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `date` | `String` | A string value to parse as a date. |
| `timeZone` | `String` | The output time zone. |
| `format` | `String` | The date format per the `SimpleDateFormat` specification. |

#### Return


`Date` --- The input string as a date.

*** ** * ** ***

### `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).

```javascript
// Creates a blob object from a string.
const data = 'GOOGLE';
const blob = Utilities.newBlob(data);

// Puts the script to sleep for 10,000 milliseconds (10 seconds).
Utilities.sleep(10000);

// Logs the blob data in byte array to the console.
console.log(blob.getBytes());
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `milliseconds` | `Integer` | The number of milliseconds to sleep. |

*** ** * ** ***

### `ungzip(blob)`

Uncompresses a `https://developers.google.com/apps-script/reference/base/blob.html` object and returns a `https://developers.google.com/apps-script/reference/base/blob.html` containing the uncompressed
data.

```javascript
const textBlob = Utilities.newBlob(
    'Some text to compress using gzip compression',
);

// Create the compressed blob.
const gzipBlob = Utilities.gzip(textBlob, 'text.gz');

// Uncompress the data.
const uncompressedBlob = Utilities.ungzip(gzipBlob);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blob` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | The `https://developers.google.com/apps-script/reference/base/blob.html` of compressed data. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- A `https://developers.google.com/apps-script/reference/base/blob.html` representing the decompressed data.

*** ** * ** ***

### `unzip(blob)`

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

```javascript
const googleFavIconUrl = 'https://www.google.com/favicon.ico';
const googleLogoUrl = 'https://www.google.com/images/srpr/logo3w.png';

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

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

// This now unzips the blobs
const files = Utilities.unzip(zip);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blob` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | The zip file blob. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- 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.

```javascript
const googleFavIconUrl = 'https://www.google.com/favicon.ico';
const googleLogoUrl = 'https://www.google.com/images/srpr/logo3w.png';

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

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

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blobs` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | A array of blobs to zip up. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- 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.

```javascript
const googleFavIconUrl = 'https://www.google.com/favicon.ico';
const googleLogoUrl = 'https://www.google.com/images/srpr/logo3w.png';

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

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

#### Parameters

| Name | Type | Description |
|---|---|---|
| `blobs` | `https://developers.google.com/apps-script/reference/base/blob-source.html` | A array of blobs to zip up. |
| `name` | `String` | The name of the zip file to be created. |

#### Return


`https://developers.google.com/apps-script/reference/base/blob.html` --- A new blob containing the inputs as an archive.

## Deprecated methods

### `jsonParse(jsonString)`


**Deprecated.** As of November 2013, replaced by `JSON.parse()`

Return an object corresponding to the JSON string passed in.

```javascript
// Returns the object { name: "John Smith", company: "Virginia Company"}
const obj = Utilities.jsonParse(
    '{"name":"John Smith","company":"Virginia Company"}',
);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `jsonString` | `String` | A String representation of a JavaScript object to deserialize. |

#### Return


`Object` --- A JavaScript object representation of the input.

*** ** * ** ***

### `jsonStringify(obj)`


**Deprecated.** As of November 2013, replaced by `JSON.stringify()`

Return a JSON string of the object passed in.

```javascript
// Logs: {"name":"John Smith","company":"Virginia Company"}
const person = {
  name: 'John Smith',
  company: 'Virginia Company',
};
const json = Utilities.jsonStringify(person);
Logger.log(json);
```

#### Parameters

| Name | Type | Description |
|---|---|---|
| `obj` | `Object` | The JavaScript object to serialize to JSON. |

#### Return


`String` --- A JSON serialized JavaScript object.