This library allows a user (or service account) to utilize the Random.org API utilizing their API Key credentials within a Google Apps Script.
In the Google online script editor, select the Resources menu item and choose Libraries.... In the "Add a library" input box, enter 1mrhlka2Ads1AgPexsqIcVJJzdEH-plJnoGux5Mojj3ZULoCjRPVqLp4i and click "Add." Choose the most recent version number.
- Follow the instructions on Random.org to get an API Key.
- Save the key in your script somewhere (GUID format)
Now, with your API Key key, we will authenticate with Random.org to get our Random instance. To do this, get the Random object from the library:
var random = Random.getRandom(key);Using this Random generator instance, we check the status of our key:
random.usage();And you can get the following example return object:
{
status: "running",
creationTime: "2018-06-26 01:00:00Z",
bitsLeft: 500000,
requestsLeft: 1000,
totalBits: 10000,
totalRequests: 20
}Can use the random object to get a random UUID
random.uuid(); // Possible result: "cff64354-e6f1-4b9f-8f9f-539edb498205"You can even get multiple UUIDs:
random.uuid(2);Result:
[
"29f453f7-bf28-4f86-bf0c-f0ad65a6b6c0",
"2605f31f-8f7a-41ab-b681-34fa9615bd84"
]- getRandom(key) ⇒
object Gets a new Random object that can generate random values.
- Random
- .integer(min, max, n, repl, base) ⇒
number|array - .decimal(precision, n, repl) ⇒
number|array - .normal(mean, stdDev, sigFig, n) ⇒
number|array - .string(length, chars, n, repl) ⇒
string|array - .uuid(n) ⇒
string|array - .blob(length, n, format) ⇒
string|array - .usage() ⇒
object
- .integer(min, max, n, repl, base) ⇒
This method generates true random integers within a user-defined range.
Returns: number | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| min | number |
The lower boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. |
| max | number |
The upper boundary for the range from which the random numbers will be picked. Must be within the [-1e9,1e9] range. |
| n | number |
How many random integers you need. Must be within the [1,1e4] range. Default: 1. |
| repl | boolean |
Specifies whether the random numbers should be picked with replacement. Default: true. |
| base | number |
Specifies the base that will be used to display the numbers. Values allowed are 2, 8, 10 and 16. Default: 10. |
This method generates true random decimal fractions from a uniform distribution across the [0,1] interval with a user-defined number of decimal places.
Returns: number | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| precision | number |
The number of decimal places to use. Must be within the [1,20] range. |
| n | number |
How many random decimal fractions you need. Must be within the [1,1e4] range. Default: 1. |
| repl | boolean |
Specifies whether the random numbers should be picked with replacement. Default: true. |
This method generates true random numbers from a Gaussian distribution (also known as a normal distribution). The form uses a Box-Muller Transform to generate the Gaussian distribution from uniformly distributed numbers.
Returns: number | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| mean | number |
The distribution's mean. Must be within the [-1e6,1e6] range. |
| stdDev | number |
The distribution's standard deviation. Must be within the [-1e6,1e6] range. |
| sigFig | number |
The number of significant digits to use. Must be within the [2,20] range. |
| n | number |
How many random numbers you need. Must be within the [1,1e4] range. Default: 1. |
This method generates true random strings.
Returns: string | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| length | number |
The length of each string. Must be within the [1,20] range. All strings will be of the same length |
| chars | string |
A string that contains the set of characters that are allowed to occur in the random strings. The maximum number of characters is 80. |
| n | number |
How many random strings you need. Must be within the [1,1e4] range. Default: 1. |
| repl | boolean |
Specifies whether the random strings should be picked with replacement. Default: true. |
This method generates version 4 true random Universally Unique IDentifiers (UUIDs) in accordance with section 4.4 of RFC 4122.
Returns: string | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| n | number |
of results to return |
This method generates Binary Large OBjects (BLOBs) containing true random data. The total size of all blobs requested must not exceed 1,048,576 bits (128 KiB).
Returns: string | array - Result or Array of Results
| Param | Type | Description |
|---|---|---|
| length | number |
The size of each blob, measured in bits. Must be within the [1,1048576] range and must be divisible by 8. |
| n | number |
How many random blobs you need. Must be within the [1,100] range. Default: 1. |
| format | string |
Specifies the format in which the blobs will be returned. Values allowed are base64 and hex. Default: 'base64'. |
This method returns information related to the the usage of a given API key.
Returns: object - API Key information
Gets a new Random object that can generate random values.
Returns: object - an authenticated interface with a Random value generator
See: https://api.random.org/json-rpc/1/
| Param | Type | Description |
|---|---|---|
| key | string |
the user private key (for authentication) |
Contributions are welcome — send a pull request! This library is a work in progress. See here for more information on contributing.
After cloning this repository, you can push it to your own private copy of this Google Apps Script project to test it yourself. See here for directions on using clasp to develop App Scripts locally.
If you want to view the source code directly on Google Apps Script, where you can make a copy for yourself to edit, click here.