Helper library
To access data from within an EdgeWorkers function, you need to use the JavaScript helper library provided by Akamai. This library uses an EdgeWorkers HTTP sub-request within an EdgeWorkers event handler to access EdgeKV data. For more information about the limits that apply to sub-requests, refer to the EdgeWorkers Resource tier limitations.
Enhanced token workflow
You need version 0.6.2 or higher of the JavaScript helper library in your EdgeWorkers code bundle to enable the enhanced token workflow capability.
Any tokens created before the token workflow enhancement was activated are not compatible with version 0.6.2 of the JavaScript helper library. For instructions on how to update your code bundle go to, Create a code bundle.
Supported operations
Review the table below for details about the supported operations and EdgeKV JavaScript APIs for each event handler.
Event handler | Supported EdgeKV operations | Supported EdgeKV JavaScript APIs |
---|---|---|
responseProvider onClientResponse OnOriginRequest OnOriginResponse onClientRequest | Read/Write/Delete | getText() getJson() putText() putTextNoWait putJson() putJsonNoWait() delete() deleteNoWait() |
To learn more about the specific HTTP events that can execute an EdgeWorkers script go to the Event handler functions section in the EdgeWorkers documentation.
Error format
When an operation is not successful an error object in the following format is thrown.
{
"failed": "whatFailed",
"status": responseStatusCode,
"body": "descriptionOfFailure"
}
Constructor
Use this Constructor to set the default namespace and group. You can make individual GET, PUT, and DELETE operations to override these default values.
new EdgeKV(namespace = "default", group = "default", num_retries_on_timeout = 0)
Parameter | Type | Description | Default Value |
---|---|---|---|
namespace | String | The default namespace to use for all GET, PUT, and DELETE operations. Refer to the Limits that apply to namespaces. | "default" |
group | String | The default group to use for all GET, PUT, and DELETE operations. Refer to the Limits that apply to groups. | "default" |
num_retries_on_timeout | Number | Specifies the number of retries to attempt when executing the getText() and getJson() methods.You can specify this parameter as a common value in the EdgeKV Constructor, or each time getText() or getJson() are invoked. If you specify it in the getText() or getJson() invocation it overrides any setting in the Constructor for that specific invocation. | 0 (indicates no retries) When using this parameter the recommended number of retries is 1 to 3. |
ew_request | Object | Optional parameter that enables access to EdgeKV data in Sandbox environments. Must be set to the Request Object passed into the EdgeWorkers event handler to enable access to sandbox data. | "null" |
sandbox_fallback | Boolean | Optional parameter that when set to true retrieves staging data if the sandbox data does not exist. When set to false, null or the specified default value is returned if the sandbox data does not exist. The fallback parameter only applies to READ operations and MUST be accompanied by setting the ew_request parameter set to the EdgeWorkers Request Object. | "false" |
Library helper methods
getText()
Gets a text value from an item in the EdgeKV database (async).
Parameters
async getText({ namespace = this.#namespace, group = this.#group, item, default_value = null, timeout = null })
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | The item key to get from the EdgeKV database. | |
default_value | String | The default value to return if a 404 response is returned from EdgeKV. | null |
timeout | Number | The maximum time, between 1 and 4000 milliseconds, to wait for the response. | null |
num_retries_on_timeout | Number | Specifies the number of retries to attempt when executing the getText() method.You can specify this parameter as a common value in the EdgeKV Constructor, or each time getText() is invoked. If you specify it in the getText() invocation it overrides any setting in the Constructor for that specific invocation. For more information see the note below. | null (indicates no retries) When using this parameter the recommended number of retries is 1 to 3. |
Each retry request is a separate, billable read request. Retry requests are not available for write (PUT) or delete (DELETE) requests. If you do not require confirmation when a request completes, you should use the NoWait variants,
putTextNoWait()
,putJsonNoWait()
, anddeleteNoWait()
to avoid any EdgeWorkers timeout issues.
try {
const edgeKv = new EdgeKV({ group: "ProductSalePrice" }); // the namespace will be "default" since it is not provided
let salePrice = await edgeKv.getText({ item: productId, default_value: "N/A" });
// use the salePrice in the page
} catch (error) {
// do something in case of an error
}
getJson()
Gets a JSON value from an item in the EdgeKV database (async).
Parameters
getJson({ namespace = this.#namespace, group = this.#group, item, default_value = null, timeout = null, num_retries_on_timeout = null})
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | The item key to get from the EdgeKV database. | |
default_value | String | The default value to return if a 404 response is returned from EdgeKV. | null |
timeout | Number | The maximum time, between 1 and 4000 milliseconds, to wait for the response. | null |
num_retries_on_timeout | Number | Specifies the number of retries to attempt when executing the getJson() method.You can specify this parameter as a common value in the EdgeKV Constructor, or each time getJson() is invoked. If you specify it in the getJson() invocation it overrides any setting in the Constructor for that specific invocation. For more information see the note below. | null (indicates no retries) When using this parameter the recommended number of retries is 1 to 3. |
Each retry request is a separate, billable read request. Retry requests are not available for write (PUT) or delete (DELETE) requests. If you do not require confirmation when a request completes, you should use the NoWait variants,
putTextNoWait()
,putJsonNoWait()
, anddeleteNoWait()
to avoid any EdgeWorkers timeout issues.
putText()
Asynchronously inserts a text value into an item if it does not already exist, or updates a value if it does exist (upsert).
Parameters
putText({ namespace = this.#namespace, group = this.#group, item, value, timeout = null })
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | The item key to put into the EdgeKV database. | |
value | String | The item text value to assign to the item in the EdgeKV database. | |
timeout | Number | The maximum time, between 1 and 4000 milliseconds, to wait for the response. | null |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
let date = new Date().toString();
await edgeKv.putText({ item: productId, value: date });
// this information can then be used to see when a product was last updated
} catch (error) {
// do something in case of an error
}
putTextNoWait()
Upserts a text value into an item in the EdgeKV database while only waiting for the request to send and not for the response.
Parameters
putTextNoWait({ namespace = this.#namespace, group = this.#group, item, value })
Parameter | Type | Description | |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | The item key to put into the EdgeKV database. | |
value | String | The item text value to assign to the item in the EdgeKV database. |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
let date = new Date().toString();
edgeKv.putTextNoWait({ item: productId, value: date });
// this information can then be used to see when a product was last updated
} catch (error) {
// do something in case of an error
}
putJson()
Upserts a JSON value into an item in the EdgeKV database (async).
Parameters
putJson({ namespace = this.#namespace, group = this.#group, item, value, timeout = null })
Parameters | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | Specifies a group other than the default. | Default value specified in Constructor. | |
item | String | The item key to put into the EdgeKV database. | |
value | JSON object | The item json value to assign to the item in the EdgeKV database. | |
timeout | Number | The maximum time, between 1 and 4000 milliseconds, to wait for the response. | null |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
let obj = {prop1:"someValue",prop2:42};
await edgeKv.putJson({ item: productId, value: obj });
// this json object can later be pulled out using getJson
} catch (error) {
// do something in case of an error
}
putJsonNoWait()
Upserts a JSON value into an item in the EdgeKV database while only waiting for the request to send and not for the response.
Parameters
putJsonNoWait({ namespace = this.#namespace, group = this.#group, item, value })
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | The item key to put into the EdgeKV database. | |
value | JSON object | The item json value to assign to the item in the EdgeKV database. |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
let obj = {prop1:"someValue",prop2:42};
edgeKv.putJsonNoWait({ item: productId, value: obj });
// this json object can later be pulled out using getJson
} catch (error) {
// do something in case of an error
}
delete()
Deletes the named item from the EdgeKV database.
Parameters
delete({ namespace = this.#namespace, group = this.#group, item, timeout = null })
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | Item key to delete from the database. | |
timeout | Number | The maximum time, between 1 and 4000 milliseconds, to wait for the response. | null |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
await edgeKv.delete({ item: productId });
} catch (error) {
// do something in case of an error
}
deleteNoWait()
Deletes the named item from the EdgeKV database while only waiting for the request to send and not for the response.
Parameters
deleteNoWait({ namespace = this.#namespace, group = this.#group, item } = {}) {
Parameter | Type | Description | Default value |
---|---|---|---|
namespace | String | Specifies a namespace other than the default. | Default value specified in Constructor. |
group | String | Specifies a group other than the default. | Default value specified in Constructor. |
item | String | Item key to delete from the database. |
try {
const edgeKv = new EdgeKV({ group: "LastUpdated" });
edgeKv.deleteNoWait({ item: productId });
} catch (error) {
// do something in case of an error
}
Updated about 1 month ago