
- Overview
- Resources
- Data
- SubCustomer
- SubProperty
- Policy
- Matches and Behaviors
- client-ip
- cookie
- geography
- header
- host-name
- http-method
- url-extension
- url-filename
- url-path
- url-querystring
- url-scheme
- url-wildcard
- access-control
- cachekey-query-args
- caching
- content-characteristics-dynamic-web-content
- content-characteristics-large-files
- content-characteristics-on-demand-streaming
- content-characteristics-live-streaming
- content-compression
- content-refresh
- downstream-caching
- geo-blacklist
- geo-whitelist
- ip-blacklist
- ip-whitelist
- modify-outgoing-request-header
- modify-outgoing-request-path
- modify-outgoing-response-header
- origin
- origin-characteristics
- origin-failover
- referer-blacklist
- referer-whitelist
- site-failover
- token-auth
- url-redirect
- Errors
Akamai Cloud Embed API v2
Add customers to access your unique Akamai Cloud Embed CDN instance, and manage policies of rules and behaviors specific to each customer.
Learn more:
Download this API’s RAML and JSON schema descriptors.
Overview
As an Akamai cloud partner, you can use the Akamai Cloud Embed (ACE) API to provide Content Delivery Network (CDN) features to your cloud customers, known as “subcustomers.”
You can configure CDN features per domain and give subcustomers the ability to buy, configure, and monitor Akamai’s CDN services directly through your portal.
In most cases, once you create one or more base configurations to support your business needs, you can use this API to support hundreds of thousands of subcustomers per base configuration.
To use this API and its core delivery, download, and video streaming capabilities, you need to add ACE to your contract. To use the acceleration features, you have to sign up for Integrated Cloud Accelerator (ICA).
NOTE: The former name of Akamai Cloud Embed was Wholesale Delivery.
Get started
To configure this API for the first time:
Contact Akamai to enable ACE for your account. If you want acceleration features, you also need to add ICA.
If your subcustomers support both HTTP and HTTPS traffic, contact Akamai to create a secure ACE base configuration and provision the necessary certificates. Akamai recommends this configuration for ACE. You can create this configuration yourself, using Property Manager in Akamai Control Center.
If your subcustomers only support HTTP traffic, contact Akamai to request a multi-domain edge hostname and create an InstantConfig property. A multi-domain edge hostname lets you use a single hostname to represent multiple web assets.
Create an origin hostname. You need to create a hostname to identify a default origin server that is separate from your subcustomer cloud origins.
Create an error page. Once you create a hostname to identify a default origin server, configure this default origin to serve an error page when subcustomers don’t configure their domain correctly.
Determine the method to use to create subcustomer IDs. Each customer in your billing system who uses your ACE implementation needs this ID. You can use any method to generate IDs as long as the IDs are unique. Akamai rolls all traffic for a particular subcustomer into this ID for billing.
Add the Sub-Customer Enablement behavior to your base configuration via Property Manager in Akamai Control Center. Once added, you need to decide which ACE features you want to offer to your subcustomers, and enable them accordingly. Your decisions determine the structure of your policy JSON going forward. (Your policy JSON is made up of rules that include both match criteria and behaviors for use with that specific subcustomer.)
If you’re using ICA, make sure you enable the Dynamic Web Content option in the Sub-Customer Enablement behavior.
If you’re using a non-secure (HTTP), Multi-Domain Edge Hostname, enable the InstantConfig behavior in your base configuration via Property Manager. InstantConfig lets you associate multiple web assets to a single property without adding each hostname to the base configuration.
Review Get Started with APIs for details on how to set up client tokens to access any Akamai API. These tokens appear as custom hostnames that look like this:
https://akzz-XXXXXXXXXXXXXXXX-XXXXXXXXXXXXXXXX.luna.akamaiapis.net
.To enable this API, choose the API service named Wholesale Delivery, and set the access level to READ-WRITE.
Interactions with other Akamai APIs
You can use the ACE API in conjunction with the following Akamai APIs:
Billing Center. This provides access to CSV-based contract usage data for accounts you can access. We provide separate reports for ACE and Integrated Cloud Acceleration (ICA), per billing period. The ACE report lists subcustomer usage (hits and bytes) by geography. The ICA report contains billing data for subcustomers that used ICA, without reference to geography.
Media Delivery Reports. Use this to review traffic, usage, and quality metrics for all of the products in the Media Delivery suite, including ACE. Currently, this API combines ACE and ICA data: If a given operation served both ACE and ICA traffic during the selected time period, the report doesn’t differentiate between the two.
Property Manager API. You can use the Property Manager API to create and update a base configuration for ACE. However, you typically only need one base configuration. For ease of use, we recommend that you use Property Manager via Control Center.
Concepts
Cloud partners. Akamai resellers or partners who provide delivery services to their customers. You, as a user of this API, are a cloud partner, also referred to simply as “partner” throughout this documentation.
Subcustomers. A cloud partner’s customers are subcustomers. Akamai does not assign individual Content Provider (CP) codes to subcustomers even though their traffic is sent over the Akamai platform. As a Cloud Partner you have access to usage detail reports for each of your subcustomers, based on the subcustomer IDs you provide Akamai.
Subcustomer ID. This is a unique ID for each subcustomer within your own billing systems. All traffic for a particular subcustomer is rolled up by this ID for billing purposes.
Base configuration. An Akamai delivery configuration that includes all of the common rules for processing end-user requests. You use the Property Manager API or GUI application to configure properties used for both ACE and ICA.
Sub-Customer Enablement behavior. In Property Manager, the
subCustomer
behavior controls which individual ACE and ICA features you can use to handle your subcustomers’ traffic. You can set up this behavior to provide access to all available features, or you can select a subset of features to define different classes of service.Content Characteristics-Dynamic Web Content behavior. Include this behavior if you want to enable specific ICA optimizations for your subcustomers.
InstantConfig behavior. If your subcustomers specifically send HTTP traffic, you have to add the instantConfig behavior to your property. This behavior, also known as Multi-Domain Configuration, lets you to associate multiple web assets to a single property without adding each hostname separately. It applies property settings to all incoming hostnames based on a DNS lookup.
Policy. Policies determine how Akamai edge servers handle a given subcustomer’s requests. A single policy is bound to a hostname. Your policy JSON is made up of rules, which contain both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Make rules unique within a policy: they can’t have identical sets of matches. A policy can also contain up to 100 behaviors.
Policy rules. Rules include both match criteria and behaviors. When an incoming request meets the match criteria in a rule, it triggers the behaviors listed in that rule. Within a rule you can use each match type and each behavior once. Also, no one rule can contain both a whitelist and blacklist behavior of a given type. For example, you can add an IP whitelist and a referrer blacklist to a rule, but you can’t have both an IP whitelist and an IP blacklist in the same rule. ACE applies rules from top to bottom, so ensure you list them from least restrictive to most restrictive. For example, you would list a match on
url-wildcard
value/*
first because it would apply to all requests, where/images/*
would only apply to a subset of requests.Policy matches. Within a rule, a match defines which subcustomer requests receive the behaviors within the rule. If a match condition for a rule is met, ACE applies the behaviors set in a rule. When constructing the
matches
array in a rule, the type of data you enter depends on the type of match. For example, if you use the query string match, you have to enter the exact string and keep case sensitivity in mind. If you use theurl-scheme
match, you enter eitherHTTP
orHTTPS
. Within a match, you cannot repeat entries in the value string.Policy behaviors. Like Property Manager, the ACE API uses behaviors to encapsulate settings to customize a configuration. Behaviors are a part of a policy’s rules. A rule can have many behaviors or only one. For the ACE API, you group rules into policies. You can have a maximum of 100 behaviors in a subcustomer policy. ACE rejects policies exceeding 100 behaviors upon submission. Within a behavior, you cannot repeat entries in the value string.
Resources
The Akamai Cloud Embed API allows you as our “partner” to manage the Content Delivery Network (CDN) features available to your customers (“subcustomers”) when using Akamai Cloud Embed or Integrated Cloud Acceleration (ICA). With this API, you can create and manage subcustomer policies and IDs.
Follow this basic workflow to create a subcustomer ID and policy:
Complete the prerequisites in Get started.
If not completed already, use Property Manager in Akamai Control Center to create a “base configuration,” and ensure that you configure the Sub-Customer Enablement behavior to meet your needs. This configuration and behavior determine baseline settings for use. (It serves as a “limiter.” It states what settings can and can’t be used in a policy for all subcustomers assigned to the configuration).
Run the Add a new subcustomer operation to apply and register a “subcustomer ID” for each of your customers.
Run the Create or update a policy operation for each subcustomer ID you need to add to your base configuration. Set up the policy with individual rules and behaviors that you want applied when ACE receives a request for that subcustomer’s content.
Test the end-to-end CDN functionality with each subcustomer. You should use a test domain to verify both the functionality and the configuration.
For the final step to go live, change applicable DNS to switch Cloud Partner websites to the Akamai platform.
API summary
Download the RAML descriptors for this API.
Operation | Method | Endpoint |
---|---|---|
Subcustomer | ||
List all subcustomers | GET | /partner-api/ |
Get a subcustomer | GET | /partner-api/ |
Add a new subcustomer | PUT | /partner-api/ |
Remove a subcustomer | DELETE | /partner-api/ |
Property | ||
List all sub-properties for a base configuration | GET | /partner-api/ |
List all subcustomer domains | GET | /partner-api/ |
Policy | ||
Get a policy | GET | /partner-api/ |
Create or update a policy | PUT | /partner-api/ |
Delete a policy | DELETE | /partner-api/ |
Get policy history | GET | /partner-api/ |
Get latest active policy | GET | /partner-api/ |
List all subcustomers
Returns a list of all
subcustomers assigned to the selected base
configuration (propertyId
).
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration. |
Status 200
application/json
Object type: SubCustomer
Download schema: subcustomerID-get-all-for-config.json
Response body:
[
{
"customerID": "abc-123",
"geo": "FR",
"subPropertyIDs": [
"www.example.com",
"www.example.biz",
"www.example.net",
"www.example.co.uk"
]
}
]
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ customers Review the list of subcustomers and their geographies returned in the SubCustomer response.
Get a subcustomer
Returns policy information for the selected subcustomer and activation network.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration. |
subcustomerId |
String | SC12345 |
The unique ID of the subcustomer. Your organization assigns this value. |
Status 200
application/json
Object type: SubCustomer
Download schema: subcustomerID-add-get.json
Response body:
{
"geo": "FR"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List customers operation and store the
customer
value, which corresponds to thesubcustomerId
URL parameter.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ customers/ {subcustomerId}
Add a new subcustomer
Add a new subcustomer ID to the
selected base configuration (propertyId
).
PUT /partner-api/
Sample: /partner-api/
Content-Type: application/json
Object type: SubCustomer
Download schema: subcustomerID-add-get.json
Request body:
{
"geo": "FR"
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration. |
subcustomerId |
String | SC12345 |
The unique ID of the subcustomer. Your organization assigns this value. |
Status 200
application/json
Object type: SubCustomer
Download schema: subcustomerID-add-get.json
Response body:
{
"geo": "FR"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.You need to provide a unique ID for the subcustomer (
subcustomerId
). As the cloud partner, it’s up to you to determine a method to create these IDs and associate them with each subcustomer. The ID can contain up to 50 alphanumeric, dot or dash characters.Make a PUT request to
/partner-api/
. You also need to include the subcustomer’sv2/ network/ {network}/ properties/ {propertyId}/ customers/ {subcustomerId} geo
(geographic region) in a PUT request body. Use the valid two letter country designation (for example,US
for United States orBR
for Brazil).Verify that the
geo
value returned in the response is accurate for the subcustomer you added.
Remove a subcustomer
Remove a specific subcustomer
using its unique subcustomerId
DELETE /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID after you create the configuration. |
subcustomerId |
String | SC12345 |
The unique ID of the subcustomer. Your organization assigns this value. |
Status 200
application/json
Download schema: subcustomerID-delete.json
Response body:
{
"description": "The subcustomer for property_id '251922' and subcustomer_id '0004-propertyfolks' was successfully deleted.",
"message": "Successfully deleted"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all subcustomers operation and store the
customerID
value, that applies to the applicable subcustomer. Use this as thesubcustomerId
URL parameter for this operation.Make a DELETE request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ customers/ {subcustomerId} Review the Message response returned to verify the deletion was successful.
List all sub-properties for a base configuration
Returns all of the domains (subPropertyID
values) for
subcustomers assigned to a selected base configuration (propertyId
)
and activation network.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
Status 200
application/json
Object type: SubProperty
Download schema: subproperty-get-all-for-property.json
Response body:
[
{
"subPropertyID": "www.example.com",
"customerID": "abc-123"
},
{
"subPropertyID": "www.example.biz",
"customerID": "abc-123"
},
{
"subPropertyID": "www.example.com.net",
"customerID": "def-456"
},
{
"subPropertyID": "www.example.com.co.uk",
"customerID": "def-456"
}
]
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties
List all subcustomer domains
Returns
domain-specific information for the selected
subcustomer domain (subPropertyID
) and activation
network.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
subcustomerId |
String | SC12345 |
The unique ID of the subcustomer. Your organization assigns this value. |
Status 200
application/json
Object type: SubProperty
Download schema: subproperty-get-all-for-subcustomer.json
Response body:
[
{
"customerID": "abc-123",
"geo": "FR",
"subPropertyIDs": [
"www.example.com",
"www.example.biz",
"www.example.net",
"www.example.co.uk"
]
}
]
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List customers operation and store the
customer
value, which corresponds to thesubcustomerId
URL parameter.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ customers/ {subcustomerId}/ sub-properties
Get a policy
Returns the policy for the selected
subcustomer domain, base configuration
(propertyId
), and activation network.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
domainName |
String | www.example.com |
The name of the subcustomer’s domain. |
Status 200
application/json
Object type: Policy
Download schema: policy-rule.json
Response body:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all sub-properties for a base configuration operation and store the value from the
subPropertyIDs
array, that corresponds to the appropriate subcustomer’scustomerID
. Use this as thedomainName
URL parameter for this operation.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties/ {domainName}/ policy Review the rule information returned in the Policy response.
Create or update a policy
Create a new subcustomer policy or update an existing one.
PUT /partner-api/
Sample: /partner-api/
Headers:
X-Customer-ID: 100-example.com
X-Custom-Metadata: 100
Content-Type: application/json
Object type: Policy
Download schema: policy-rule.json
Request body:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
domainName |
String | www.example.com |
The name of the subcustomer’s domain. |
Status 200
application/json
Object type: Policy
Download schema: policy-rule.json
Response body:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all sub-properties for a base configuration operation and store the value from the
subPropertyIDs
array, that corresponds to the appropriate subcustomer’scustomerID
. Use this as thedomainName
URL parameter for this operation.Include a valid, registered subcustomer ID as the
X-Customer-ID
header. You can also optionally specify a string up to 50 characters in length to serve as theX-Custom-Metadata
header, for use in billing and reporting.Make a PUT request to
/partner-api/
. Include a properly formatted request body with rules that consist of proper match criteria, and the behaviors that you want applied when a request for the subcustomer’s content meets that criteria.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties/ {domainName}/ policy Review the information returned in the Policy response.
Delete a policy
Deletes the currently active policy file for the selected subcustomer domain and activation network.
DELETE /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
domainName |
String | www.example.com |
The name of the subcustomer’s domain. |
Status 200
application/json
Download schema: policy-delete.json
Response body:
{
"message": "Successfully deleted",
"description": "The policy was successfully deleted.",
"successInstanceId": "a123bcedfg45"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all sub-properties for a base configuration operation and store the value from the
subPropertyIDs
array, that corresponds to the appropriate subcustomer’scustomerID
. Use this as thedomainName
URL parameter for this operation.Make a DELETE request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties/ {domainName}/ policy Review the Message response returned to verify the deletion was successful.
Get policy history
Returns policy change
information for the selected subcustomer domain,
base configuration (propertyId
), and activation
network.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
domainName |
String | www.example.com |
The name of the subcustomer’s domain. |
Status 200
application/json
Object type: Policy
Download schema: policy-rule-history.json
Response body:
{
"policy": {
"rules": [
{
"behaviors": [
{
"name": "origin",
"params": {
"cacheKeyType": "digital_property",
"cacheKeyValue": "-",
"digitalProperty": "sportsguys.wsdtest.akalab.com",
"hostHeaderType": "digital_property",
"hostHeaderValue": "-",
"originDomain": "sportsguys.wsdtest.akalab.com.s3-website-us-west-1.amazonaws.com"
},
"value": "-"
}
],
"matches": [
{
"name": "http-method",
"value": "GET"
}
]
},
{
"behaviors": [
{
"name": "caching",
"type": "fixed",
"value": "1h"
}
],
"matches": [
{
"name": "url-extension",
"value": "jpg"
}
]
},
{
"behaviors": [
{
"name": "caching",
"type": "fixed",
"value": "1d"
}
],
"matches": [
{
"name": "url-extension",
"value": "mp4"
}
]
}
]
},
"update_timestamp": 1440722458,
"version": 1
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all sub-properties for a property ID operation and store the appropriate value from the
subPropertyIDs
array, which corresponds to thedomainName
URL parameter.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties/ {domainName}/ policy/ history Review the rule information returned in the Policy response.
The response includes up to 100 of the most recent versions, not including the current version. If there are more than 100 versions of a policy, ACE discards the oldest policy. (For example, version 101 replaces version 1.)
Get latest active policy
Returns the latest activated
version of the policy, one with an activationStatus
of
ACTIVE
. If no active version exists, the API returns a
404 error.
GET /partner-api/
Sample: /partner-api/
Parameter | Type | Sample | Description |
---|---|---|---|
URL path parameters | |||
network |
Enumeration | production |
The network for the policy, either staging for the testing network, or production for the live network. |
propertyId |
String | a123bcdefg45 |
The ID number of the base configuration file. Akamai Cloud Embed (ACE) automatically generates this ID when the configuration is created. |
domainName |
String | www.example.com |
The name of the subcustomer’s domain. |
Status 200
application/json
Object type: Policy
Download schema: policy-rule.json
Response body:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Determine which
network
you want to gather information from. You can choosestaging
(testing) orproduction
(live).Contact your Akamai account representative for the
propertyId
assigned to the applicable base configuration.Run the List all sub-properties for a property ID operation and store the appropriate value from the
subPropertyIDs
array, which corresponds to thedomainName
URL parameter.Make a GET request to
/partner-api/
.v2/ network/ {network}/ properties/ {propertyId}/ sub-properties/ {domainName}/ policy/ active Review the rule information returned in the Policy response.
Data
This section shows you the data model for the Akamai Cloud Embed API. The main “{Object}” sections reveal an example of the JSON returned for a GET call. The “{Object} Members” sub-sections illustrate elements that are required or optional, based on the call method. For example, “required” indicates the element must be used in the request body for a PUT method call, and it is always included in the response for a GET call.
Download the JSON schemas for this API.
The data schema tables below list membership requirements as follows:
✓ | Member is required in requests, or always present in responses, even if its value is empty or null . |
○ | Member is optional, and may be omitted in some cases. |
✗ | Member is out of scope, and irrelevant to the specified interaction context. If you include the member in that context, it either triggers an error, or is ignored. |
SubCustomer
Allows you to add or update a subcustomer.
Download schema:
subcustomerID-add-get.json
Sample GET response:
[
{
"customerID": "abc-123",
"geo": "FR",
"subPropertyIDs": [
"www.example.com",
"www.example.biz",
"www.example.net",
"www.example.co.uk"
]
}
]
SubCustomer members
Member | Type | Required | Description |
---|---|---|---|
SubCustomer : Allows you to add or update a subcustomer. |
|||
geo |
String | ✓ | The geographic location of the subcustomer. |
SubProperty
Lists ID, domain, and geographic information for a subproperty, which is the subcustomer’s domain.
Download schema:
subproperty-get-all-for-subcustomer.json
Sample GET response:
[
{
"subPropertyID": "www.example.com",
"customerID": "abc-123"
},
{
"subPropertyID": "www.example.biz",
"customerID": "abc-123"
},
{
"subPropertyID": "www.example.com.net",
"customerID": "def-456"
},
{
"subPropertyID": "www.example.com.co.uk",
"customerID": "def-456"
}
]
SubProperty members
Member | Type | Required | Description |
---|---|---|---|
SubProperty : Lists ID, domain, and geographic information for a subproperty, which is the subcustomer’s domain. |
|||
customerID |
String | ○ | The ID of the customer assigned to the subproperty. |
geo |
String | ○ | The geographic location of the subcustomer. |
subPropertyID |
String | ○ | A unique string representing the subcustomer’s domain. |
Policy
Encapsulates rules consisting of match criteria and resulting behavior settings Akamai Cloud Embed (ACE) applies for a specific subcustomer.
Download schema:
policy-rule.json
, policy-rule-history.json
Sample GET response:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Sample of a GET on an older policy:
{
"policy": {
"rules": [
{
"behaviors": [
{
"name": "origin",
"params": {
"cacheKeyType": "digital_property",
"cacheKeyValue": "-",
"digitalProperty": "sportsguys.wsdtest.akalab.com",
"hostHeaderType": "digital_property",
"hostHeaderValue": "-",
"originDomain": "sportsguys.wsdtest.akalab.com.s3-website-us-west-1.amazonaws.com"
},
"value": "-"
}
],
"matches": [
{
"name": "http-method",
"value": "GET"
}
]
},
{
"behaviors": [
{
"name": "caching",
"type": "fixed",
"value": "1h"
}
],
"matches": [
{
"name": "url-extension",
"value": "jpg"
}
]
},
{
"behaviors": [
{
"name": "caching",
"type": "fixed",
"value": "1d"
}
],
"matches": [
{
"name": "url-extension",
"value": "mp4"
}
]
}
]
},
"update_timestamp": 1440722458,
"version": 1
}
Sample of a GET on the latest active policy:
{
"rules": [
{
"matches": [
{
"name": "http-method",
"value": "GET"
}
],
"behaviors": [
{
"params": {
"originBasePath": "/",
"cacheKeyValue": "-",
"digitalProperty": "www.example.com",
"cacheKeyType": "origin",
"httpPort": 80,
"hostHeaderValue": "-",
"originDomain": "www.example.com",
"hostHeaderType": "origin"
},
"name": "origin",
"type": "-",
"value": "-"
},
{
"name": "content-refresh",
"type": "fixed",
"value": "1m"
}
]
}
],
"activationStatus": "ACTIVE"
}
Policy members
Member | Type | PUT | GET | Description | ||||
---|---|---|---|---|---|---|---|---|
Policy : Encapsulates rules consisting of match criteria and resulting behavior settings Akamai Cloud Embed (ACE) applies for a specific subcustomer. |
||||||||
activationStatus |
Enumeration | ○ | ✗ | The current propagation status of the policy. This can be PROPAGATING for a policy that is still being processed, ACTIVE for a policy that has successfully completed propagation, or ACTIVATION_FAILED for a policy that encountered an error during propagation. Get the policy to check its configuration and update the policy to resubmit it for propagation. |
||||
rules |
Policy. |
✓ | ○ | The set of matches and behaviors for this subcustomer policy. | ||||
Policy.rules[] : The set of matches and behaviors for this subcustomer policy. |
||||||||
behaviors |
Policy. |
✓ | ○ | The behaviors to apply to requests that meet the match criteria set in this policy. | ||||
matches |
Policy. |
✓ | ✗ | The criteria that identify which requests to process. When a request matches the criteria, ACE applies the behaviors to the request. | ||||
Policy.rules[].behaviors[] : The behaviors to apply to requests that meet the match criteria set in this policy. |
||||||||
name |
Enumeration | ✓ | ○ | The specific behavior you want to apply to incoming requests that meet the associated match criteria. | ||||
params |
Object | ○ | ○ | The set of options that determine how the behavior operates. | ||||
type |
String | ✓ | ○ | The format to use for the value element. |
||||
value |
String | ✓ | ○ | The values to use for the selected behavior. | ||||
Policy.rules[].matches[] : The criteria that identify which requests to process. When a request matches the criteria, ACE applies the behaviors to the request. |
||||||||
name |
Enumeration | ✓ | ✗ | The specific match criteria that must be met to apply the behaviors you define. |
||||
negated |
Boolean | ○ | ✗ | If set to true , ACE applies the behaviors set in this rule when an incoming request does not meet the match criteria. |
||||
value |
String | ✓ | ✗ | The value to match. |
Matches and Behaviors
A match defines the criteria to be met in a request for subcustomer content in order to apply the behaviors set in a rule.
Behaviors determine the settings ACE applies to the delivery of subcustomer content. Akamai Cloud Embed (ACE) applies a behavior’s settings when a request that meets the rule’s match criteria is received for a subcustomer’s content.
- access-control
- cachekey-query-args
- caching
- content-characteristics (for dynamic web content)
- content-characteristics (for large files)
- content-characteristics (for on-demand streaming)
- content-characteristics (for live streaming)
- content-compression
- content-refresh
- downstream-caching
- geo-blacklist
- geo-whitelist
- ip-blacklist
- ip-whitelist
- modify-outgoing-request-header
- modify-outgoing-request-path
- modify-outgoing-response-header
- origin
- origin-characteristics
- origin-failover
- referer-blacklist
- referer-whitelist
- site-failover
- token-auth
- url-redirect
client-ip
Include this to match using the IP address assigned to the requesting client. You can specify individual IP addresses, or CIDR blocks (that express a range of addresses).
Download schema:
client-ip-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "client-ip",
"value": "-",
"params": {
"ipOrCidrList": [
"1.2.3.4",
"5.6.7.8",
"192.168.100.14/24",
"2001:db8:abcd:8000::/50"
],
"source": "both",
"ipFromHeader": "all"
},
"negated": true
}
],
"behaviors": []
}
client-ip members
Member | Type | Required | Description |
---|---|---|---|
client-ip : Include this to match using the IP address assigned to the requesting client. You can specify individual IP addresses, or CIDR blocks (that express a range of addresses). |
|||
name |
Enumeration | ✓ | Enter client-ip to match based on the requesting client’s IP address. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
params |
client-ip. |
✓ | Specifies each set of addresses along with criteria to match them. |
value |
String | ✓ | All match criteria require the value member, but client-ip does not use one. Specify a dash for this member (- ). |
client-ip.params[] : Specifies each set of addresses along with criteria to match them. |
|||
ipFromHeader |
Enumeration | ○ | When matching the X-Forwarded-For header, specifies which IP address to match in the list, either the first IP address, or all to match any. |
ipOrCidrList |
Array | ✓ | Enter one or more specific IP addresses or CIDR blocks of IP addresses. If a requesting client is assigned to one of these IP addresses, the behaviors set in this policy are applied. For example, ["1.2.3.4", "5.6.7.8", "192.168.100.14/24", "2001:db8:abcd:8000::/50"] . |
source |
Enumeration | ○ | Specifies where to find the IP address, either connectingIp for the requesting client’s IP address, headers for the X-Forwarded-For header, or both to match either location. |
cookie
Include this match to define specific cookie names for use when matching on an incoming request.
Download schema:
cookie-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "cookie",
"value": "cookie-name cookie-value1 cookie-value2",
"negated": true
}
],
"behaviors": []
}
cookie members
Member | Type | Required | Description |
---|---|---|---|
cookie : Include this match to define specific cookie names for use when matching on an incoming request. |
|||
name |
Enumeration | ✓ | Enter cookie to use cookie names when matching on the incoming request. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Specifies the case-insensitive cookie name to match on. You can follow the cookie name with a space-delimited list of cookie values to match against, all of which are case-sensitive. Cookie name and cookie values do not support white spaces. Currently, the + ! ( ) [ ] { } characters are not supported, even though they are normally supported for use in cookies. For example, cookiename cookievalue1 cookievalue2 . |
geography
Use this match to test the requesting client’s location, either by continent, country, region, or designated market area (DMA). Each subcustomer policy can include up to ten geography
matches.
Download schema:
geography-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "geography",
"value": "-",
"params": {
"continent": [
"AS",
"EU"
],
"country": [
"IN",
"CA"
],
"region": [
"US:CA",
"US:TX"
],
"dma": [
500,
501,
502
],
"source": "both",
"ipFromHeader": "first"
}
}
],
"behaviors": []
}
geography members
Member | Type | Required | Description |
---|---|---|---|
geography : Use this match to test the requesting client’s location, either by continent, country, region, or designated market area (DMA). Each subcustomer policy can include up to ten geography matches. |
|||
name |
Enumeration | ✓ | Enter geography to match based on the requesting client’s geographic location. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
params |
geography. |
✓ | Specifies any geographic area to match. You need to include at least one continent , country , region , or dma type, and at least one value for each type, if specified. Any specified value matches, so if you include NA (North America) as a continent , you don’t need to include US as a country . |
value |
String | ✓ | All match criteria require the value member, but geography does not use one. Specify a dash for this member (- ). |
geography.params : Specifies any geographic area to match. You need to include at least one continent , country , region , or dma type, and at least one value for each type, if specified. Any specified value matches, so if you include NA (North America) as a continent , you don’t need to include US as a country . |
|||
continent |
Array | ○ | Specify a list of two-letter continents to match: AF for Africa, AS for Asia, EU for Europe, NA for North America, OC for Oceania, SA for South America, and OT for all others. |
country |
Array | ○ | Specify a list of two-letter countries to match. For example, US for United States and IN for India. A list of supported Country Codes is available for download on Akamai Control Center. |
dma |
Array | ○ | This only applies to the United States. Specify a list of numeric designations as string values to serve as designated market area (DMA) codes. A DMA is a specific Nielsen Media Research area in which the population can receive the same, or similar Internet media offerings. A list of supported DMA Codes is available on Control Center. |
ipFromHeader |
Enumeration | ○ | When matching the X-Forwarded-For header for the source , specifies which geographic client IP information to match, either the first client IP listed for a specified geographic location, or all to match any. The default is first . |
region |
Array | ○ | Specify a list of regions to match. Use the two letter designation for a specific region (state or territory), prefaced with the applicable country and a colon. For example, US:CA for California, United States or CA:BC for British Columbia, Canada. A list of supported Country Codes and State or Region Codes is available on Control Center. |
source |
Enumeration | ○ | Specifies where to find the geographic information, either connectingIp to use the requesting client’s IP address, headers to use the X-Forwarded-For header, or both to match either location. The default is both . |
header
Associated behaviors are applied if a header or header value you specify in this match criteria are included with a request.
Download schema:
header-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "header",
"value": "header-name header-value1 header-value2",
"negated": false
}
],
"behaviors": []
}
header members
Member | Type | Required | Description |
---|---|---|---|
header : Associated behaviors are applied if a header or header value you specify in this match criteria are included with a request. |
|||
name |
Enumeration | ✓ | Enter header to match on an incoming request header or header value. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter a header name, and optionally include an associated header value, for the match (for example, Some-Header-Name or Some-Header-Name "some string value" "another value" or ). Separate multiple header value entries with spaces. Header values are also case sensitive. |
host-name
Include this to match on hostnames listed in the incoming request’s Host header.
Download schema:
host-name-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "host-name",
"value": "host-name1 host-name2 host-name3",
"negated": false
}
],
"behaviors": []
}
host-name members
Member | Type | Required | Description |
---|---|---|---|
host-name : Include this to match on hostnames listed in the incoming request’s Host header. |
|||
name |
Enumeration | ✓ | Enter host-name to match on hostnames listed in the incoming request’s Host header. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter a space-separated list of hostnames to match. You can use the ? and * wildcards with this match value. |
http-method
Include this to match on a set of HTTP methods included in a client request.
Download schema:
http-method-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "http-method",
"value": "PUT POST",
"negated": true
}
],
"behaviors": []
}
http-method members
Member | Type | Required | Description |
---|---|---|---|
http-method : Include this to match on a set of HTTP methods included in a client request. |
|||
name |
Enumeration | ✓ | Enter http-method to match based on HTTP method. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter the HTTP methods to match on, separated by spaces. The following values are supported: GET , HEAD , POST , PUT , DELETE , OPTIONS , TRACE , and CONNECT . |
url-extension
Include this to match on the extension in the incoming request. This match criteria has no effect on URL paths that do not include a file extension.
Download schema:
url-extension-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-extension",
"value": "jpg png gif",
"negated": false
}
],
"behaviors": []
}
url-extension members
Member | Type | Required | Description |
---|---|---|---|
url-extension : Include this to match on the extension in the incoming request. This match criteria has no effect on URL paths that do not include a file extension. |
|||
name |
Enumeration | ✓ | Enter url-extension to match on the extension in the incoming request. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter the filename extensions to match on, separated by spaces. This string cannot be empty and entries are case sensitive. |
url-filename
Include this to match on the filename and extension included in the incoming request.
Download schema:
url-filename-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-filename",
"value": "filename.ext myfile.ext",
"negated": false
}
],
"behaviors": []
}
url-filename members
Member | Type | Required | Description |
---|---|---|---|
url-filename : Include this to match on the filename and extension included in the incoming request. |
|||
name |
Enumeration | ✓ | Enter url-filename to match on the filename and extension included in the incoming request. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter a space-separated list of filenames to match. Wildcards are not supported. (Include the full name of the target file.) The filename can be in any subdirectory or URL path. For example, filename.ext matches on both /filename.ext and /path/to/filename.ext . |
url-path
Include this to match on the first path component in the incoming request. The first path component is the section directly after the base URL.
Download schema:
url-path-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-path",
"value": "new-files old-files",
"negated": false
}
],
"behaviors": []
}
url-path members
Member | Type | Required | Description |
---|---|---|---|
url-path : Include this to match on the first path component in the incoming request. The first path component is the section directly after the base URL. |
|||
name |
Enumeration | ✓ | Enter url-path to match on the first path component in the incoming request. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter a space-separated list of path names to match on. Do not include slashes with your entry. This match is case sensitive and does not support wildcard characters. For example, entering new-files old-files matches on all URI paths that begin with /new-files/ or /old-files/ , like /new-files/dir1/dir2/filename.ext . |
url-querystring
Include this to match on a combination of query string parameters and their values.
Download schema:
url-querystring-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-querystring",
"params": [
{
"key": "test*"
},
{
"key": "version*",
"values": "beta* *test*"
},
{
"key": "mode",
"values": "bypass"
}
],
"negated": false
}
],
"behaviors": []
}
url-querystring members
Member | Type | Required | Description |
---|---|---|---|
url-querystring : Include this to match on a combination of query string parameters and their values. |
|||
name |
Enumeration | ✓ | Enter url-querystring to match on a combination of query string parameters and their values. |
params |
url-querystring. |
○ | The parameters that define how you want to handle query strings for your implementation. |
url-querystring.params[] : The parameters that define how you want to handle query strings for your implementation. |
|||
key |
String | ○ | Enter the query string to match on. You can use the ? and * wildcards with your entry. |
value |
String | ○ | Enter the query string values to match on, separated by spaces. You can use the ? and * wildcards with this match value. |
url-scheme
Include this to match on the protocol or scheme (HTTP or HTTPS) of an incoming request.
Download schema:
url-scheme-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-scheme",
"value": "HTTP",
"negated": true
}
],
"behaviors": []
}
url-scheme members
Member | Type | Required | Description |
---|---|---|---|
url-scheme : Include this to match on the protocol or scheme (HTTP or HTTPS) of an incoming request. |
|||
name |
Enumeration | ✓ | Enter url-scheme to match on the protocol or scheme (HTTP or HTTPS) of an incoming request. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
Enumeration | ✓ | Enter either HTTP or HTTPS depending on the protocol you want to match on. |
url-wildcard
Include this match to use wildcards when matching on the incoming request path, minus any query strings. This match type only supports the *
wildcard.
Download schema:
url-wildcard-match.json
Sample inclusion for this match in a PUT policy operation:
{
"matches": [
{
"name": "url-wildcard",
"value": "/styles/* /images/baseball.png",
"negated": false
}
],
"behaviors": []
}
url-wildcard members
Member | Type | Required | Description |
---|---|---|---|
url-wildcard : Include this match to use wildcards when matching on the incoming request path, minus any query strings. This match type only supports the * wildcard. |
|||
name |
Enumeration | ✓ | Enter url-wildcard to use wildcards when matching on the incoming request path, minus query strings. |
negated |
Boolean | ○ | If set to true , Akamai Cloud Embed (ACE) applies the behaviors set in the subcustomer policy when an incoming request does not meet the match criteria. |
value |
String | ✓ | Enter the path to match on. If you do not include a wildcard, the incoming request must match the value exactly as entered. |
access-control
Include this behavior to allow or deny client requests based on what’s specified as the matches
criteria.
Download schema:
access-control-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "access-control",
"type": "denied",
"value": "deny-protocol"
}
]
}
access-control members
Member | Type | Required | Description |
---|---|---|---|
access-control : Include this behavior to allow or deny client requests based on what’s specified as the matches criteria. |
|||
name |
Enumeration | ✓ | Enter access-control to deny client requests based on any of the available match conditions. |
type |
Enumeration | ✓ | Either deny or allow an incoming request that matches on this rule. |
value |
String | ✓ | Enter strings of up to 64 characters to annotate logs with the approval or denial reason. Alphanumeric characters, dashes, and underscores are valid. For a type of allow , you can also use the * wildcard character. Separate strings with spaces. |
cachekey-query-args
Include this behavior to determine how query string arguments within an incoming request should be handled.
Download schema:
cachekey-query-args-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "cachekey-query-args",
"type": "include",
"value": "product=1"
}
]
}
cachekey-query-args members
Member | Type | Required | Description |
---|---|---|---|
cachekey-query-args : Include this behavior to determine how query string arguments within an incoming request should be handled. |
|||
name |
Enumeration | ✓ | Enter cachekey-query-args to define how query-string arguments are handled when creating the cache key for the Akamai edge server. |
type |
Enumeration | ✓ | Options for handling query-string arguments. Use include-all to include all query-string values in the cache key. Use include to only append the query arguments listed in the cache key’s value attribute. Use ignore-all to remove all query-string arguments from the incoming request. Use ignore to not include the query arguments listed in the value attribute in the cache key. |
value |
String | ✓ | If using include or ignore as the caching type, list the query strings to match on. The match is case sensitive. Use spaces to separate entries. Add an equal sign to the value to match the query string argument exactly and also extend the value of the query argument. For example, entering product=1 matches both product=1 and product=123 but not product=234 . Not required for the include-all and ignore-all type settings. |
caching
Include this behavior to define time-to-live (TTL) cache settings for subcustomers.
Download schema:
caching-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "caching",
"type": "fixed",
"value": "86400s"
}
]
}
caching members
Member | Type | Required | Description |
---|---|---|---|
caching : Include this behavior to define time-to-live (TTL) cache settings for subcustomers. |
|||
name |
Enumeration | ✓ | Enter caching to configure the time-to-live (TTL) settings for a subcustomer based on specific match conditions. |
type |
Enumeration | ✓ | Select the type of cache response to use. Choose no-store to never cache the response and evict any existing cache entry; bypass-cache to never cache the response and retain the existing cache entry; fixed to cache the response for the time period defined in value ; honor to cache based on the values in the cache-control and expires headers; honor-cc to cache based on the values in the cache-control header; or honor-expires to cache based on the values in the expires header. For the honor-based options, objects currently in cache may be used with the current request. Also, if the response doesn’t include the Cache-Control or Expires header, the object is cached based on the time listed in the value parameter. For the honor and honor-cc options, if the Cache-Control header includes a no-store or no-cache directive, the Akamai server doesn’t cache the response. No caching occurs if the Expires header has an RFC 2616 time string in the past or includes -1 , which helps prevent downstream caching. |
value |
String | ✓ | Ignored for the no-store and bypass-cache types. For all other type settings, enter a simple duration string, which is an integer followed by a specifier to represent seconds (s ), minutes (m ), hours (h ), or days (d ). For example: 86400s , or 1440m , or 24h , or 1d all represent a TTL setting of one day. |
content-characteristics-dynamic-web-content
Include the content-characteristics
behavior and set the type
to dynamic-web-content
if you’re using Integrated Cloud Acceleration, to use SureRoute to optimize the forward path to the origin server. It controls embedded object pre-fetching, situational image compression, and Real User Monitoring (RUM) capabilities.
Download schema:
content-char-dynamic-web-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-characteristics",
"type": "dynamic-web-content",
"value": "-",
"params": {
"mobileImageCompressionEnabled": true,
"prefetchEnabled": false,
"realUserMonitoringEnabled": true,
"sureRouteTestObjectPath": "/sureroute"
}
}
]
}
content-characteristics-dynamic-web-content members
Member | Type | Required | Description |
---|---|---|---|
content-characteristics-dynamic-web-content : Include the content-characteristics behavior and set the type to dynamic-web-content if you’re using Integrated Cloud Acceleration, to use SureRoute to optimize the forward path to the origin server. It controls embedded object pre-fetching, situational image compression, and Real User Monitoring (RUM) capabilities. |
|||
name |
Enumeration | ✓ | Enter content-characteristics , the behavior that includes this optimization. |
params |
content-characteristics-dynamic-web-content. |
○ | Optimization settings for this behavior. |
type |
Enumeration | ✓ | Enter dynamic-web-content to use Akamai’s SureRoute feature to optimize the forward path to the origin server. |
value |
String | ✓ | Ignored for this behavior. For consistency, enter a dash (- ). |
content-characteristics-dynamic-web-content.params : Optimization settings for this behavior. |
|||
mobile |
Boolean | ○ | Enable or disable JPEG compression based on mobile network conditions. |
prefetchEnabled |
Boolean | ○ | Inspects HTML responses and prefetches embedded objects in HTML files. Prefetching works on any page that includes <img> , <script> , or <link> tags that specify relative paths. It also works when the resource hostname matches the request domain in the HTML file, and it is part of a fully qualified URI. When set to true , edge servers prefetch objects with the following file extensions: aif , aiff , au , avi , bin , bmp , cab , carb , cct , cdf , class , css , doc , dcr , dtd , exe , flv , gcf , gff , gif , grv , hdml , hqx , ico , ini , jpeg , jpg , js , mov , mp3 , nc , pct , pdf , png , ppc , pws , swa , swf , txt , vbs , w32 , wav , wbmp , wml , wmlc , wmls , wmlsc , xsd , and zip . |
sure |
String | ○ | Enable SureRoute by entering a valid path to the test object on your origin. A valid test object is between 4 KB to 12 KB compressed and requires no authorization. SureRoute looks for the optimal route between an edge server and an origin server. |
content-characteristics-large-files
Include the content-characteristics
behavior and set the type
to large-files
to optimize the delivery of large file downloads of up to 1.8 GB. This behavior uses partial object caching with pre-fetched object data.
As a best practice, only use this behavior if you serve large files. Otherwise, the Akamai platform may send additional requests to your origin. When using Large File Optimization, if an object doesn’t meet the minimum size criterion of 10 MB, the platform requests the entire object from the origin.
Download schema:
content-char-large-file-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-characteristics",
"type": "large-files",
"value": "-",
"params": {
"objectSize": "10mbto100mb"
}
}
]
}
content-characteristics-large-files members
Member | Type | Required | Description |
---|---|---|---|
content-characteristics-large-files : Include the content-characteristics behavior and set the type to large-files to optimize the delivery of large file downloads of up to 1.8 GB. This behavior uses partial object caching with pre-fetched object data. As a best practice, only use this behavior if you serve large files. Otherwise, the Akamai platform may send additional requests to your origin. When using Large File Optimization, if an object doesn’t meet the minimum size criterion of 10 MB, the platform requests the entire object from the origin. |
|||
name |
Enumeration | ✓ | Enter content-characteristics , the behavior that includes this optimization. |
params |
content-characteristics-large-files. |
○ | The parameters that define how you want to handle file optimization for your implementation. |
type |
Enumeration | ✓ | Enter large-files to optimize the delivery of large file downloads of up to 1.8 GB. |
value |
String | ✓ | Ignored for this behavior. For consistency, enter a dash (- ). |
content-characteristics-large-files.params : The parameters that define how you want to handle file optimization for your implementation. |
|||
objectSize |
Enumeration | ○ | Options include: lt1mb for objects less than 1 MB, 1mbto10mb for objects 1 MB to 10 MB, 10mbto100mb for objects 10 MB to 100 MB, and gt100mb for objects 100 MB and larger. Both 10mbto100mb and gt100mb enable Large File Optimization. Using lt1mb or 1mbto10mb disables partial object caching and prevents the platform from serving large objects. |
content-characteristics-on-demand-streaming
Include the content-characteristics
behavior and set the type
to streaming-video-on-demand
to optimize caching and network timeout conditions for on-demand video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type
headers, and network timeout settings.
Download schema:
content-char-vod-streaming-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-characteristics",
"type": "streaming-video-on-demand",
"value": "-",
"params": {
"segmentDurationDASH": "3.0",
"segmentDurationHDS": "4.0",
"segmentDurationHLS": "7.0",
"segmentDurationSmooth": "3.0",
"prefetch": {
"originAssist": true
}
}
}
]
}
content-characteristics-on-demand-streaming members
Member | Type | Required | Description |
---|---|---|---|
content-characteristics-on-demand-streaming : Include the content-characteristics behavior and set the type to streaming-video-on-demand to optimize caching and network timeout conditions for on-demand video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings. |
|||
name |
Enumeration | ✓ | Specify content-characteristics , the behavior that includes this optimization. |
params |
content-characteristics-on-demand-streaming. |
○ | The parameters that define how you want to handle on-demand video streaming. |
type |
Enumeration | ✓ | Specify streaming-video-on-demand to optimize cache and network timeout conditions for on-demand video content. |
value |
String | ✓ | Ignored for this behavior. For consistency, enter a dash (- ). |
content-characteristics-on-demand-streaming.params : The parameters that define how you want to handle on-demand video streaming. |
|||
prefetch |
content-characteristics-on-demand-streaming. |
○ | To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media. |
segment |
Number | ○ | The duration in seconds for Dynamic Adaptive Streaming over HTTP (DASH) media segments for this subcustomer. The supported range is 0 to 15 , with only one decimal place allowed. If you omit this member, ACE uses the duration set for DASH Segment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default segment duration for DASH (6.0 seconds). |
segment |
Number | ○ | The duration in seconds for HTTP Dynamic Streaming (HDS) media fragments for this subcustomer. The supported range is 0 to 15 , with only one decimal place allowed. If you omit this member, ACE uses the duration set for HDS Fragment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default fragment duration for HDS (6.0 seconds). |
segment |
Number | ○ | The duration in seconds for HTTP Live Streaming (HLS) media segments. The supported range is 0 to 15 , with only one decimal place allowed. For recommended best practices, see Apple Technical Note 2224. If you omit this member, ACE uses the duration set for HLS Segment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default segment duration for HLS (10.0 seconds). |
segment |
Number | ○ | The duration in seconds for Microsoft Smooth Streaming media fragments. The supported range is 0 to 15 , with only one decimal place allowed. If you omit this member, ACE uses the duration set for Smooth Fragment Duration in the Content Characteristics - Streaming Video On Demand behavior in the assigned base configuration. Otherwise, ACE uses the default fragment duration for Smooth (2.0 seconds). |
content-characteristics-on-demand-streaming.params.prefetch : To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media. |
|||
originAssist |
Boolean | ○ | This enables prefetching using the origin-assist scheme. When Akamai fetches an object from an origin, the response needs to include a new header that lists the next object in the sequence. Akamai can read this information and prefetch this object. This scheme relies on assistance from your “intelligent” origin to trigger prefetching. Requirements and setup of an origin are explained in the Akamai Cloud Embed - Implementation Guide. |
content-characteristics-live-streaming
Include the content-characteristics
behavior and set the type
to streaming-video-live
to optimize caching and network timeout conditions for live video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type
headers, and network timeout settings.
Download schema:
content-char-live-streaming-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-characteristics",
"type": "streaming-video-live",
"value": "-",
"params": {
"segmentDurationDASH": "3.0",
"segmentDurationHDS": "4.0",
"segmentDurationHLS": "7.0",
"segmentDurationSmooth": "3.0",
"prefetch": {
"originAssist": true
}
}
}
]
}
content-characteristics-live-streaming members
Member | Type | Required | Description |
---|---|---|---|
content-characteristics-live-streaming : Include the content-characteristics behavior and set the type to streaming-video-live to optimize caching and network timeout conditions for live video content. The Akamai platform examines the URI file extension and path for the media format. It then automatically optimizes cache efficiency, time-to-live, automated failover, downstream Content-Type headers, and network timeout settings. |
|||
name |
Enumeration | ✓ | Specify content-characteristics , the behavior that includes this optimization. |
params |
content-characteristics-live-streaming. |
○ | The parameters that define how you want to handle live video streaming. |
type |
Enumeration | ✓ | Specify streaming-video-live to optimize delivery for live video content. |
value |
String | ✓ | Ignored for this behavior. For consistency, enter a dash (- ). |
content-characteristics-live-streaming.params : The parameters that define how you want to handle live video streaming. |
|||
prefetch |
content-characteristics-live-streaming. |
○ | To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media. |
segment |
Number | ○ | The duration in seconds for Dynamic Adaptive Streaming over HTTP (DASH) media segments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default segment duration for DASH (6.0 seconds). |
segment |
Number | ○ | The duration in seconds for HTTP Dynamic Streaming (HDS) media fragments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default fragment duration for HDS (6.0 seconds). |
segment |
Number | ○ | The duration in seconds for HTTP Live Streaming (HLS) media segments. The supported range is 0 to 10, with only one decimal place allowed. For recommended best practices, see Apple Technical Note 2224. If you omit this member, ACE uses the default segment duration for HLS (10.0 seconds). |
segment |
Number | ○ | Duration in seconds for Microsoft Smooth Streaming media fragments. The supported range is 0 to 10, with only one decimal place allowed. If you omit this member, ACE uses the default fragment duration for Smooth (2.0 seconds). |
content-characteristics-live-streaming.params.prefetch : To reduce delivery time, segment prefetching places target media content at the edge to anticipate end-user requests. Note: You can’t use prefetch with HDS format media. |
|||
originAssist |
Boolean | ○ | This enables prefetching using the origin-assist scheme. When Akamai fetches an object from an origin, the response needs to include a new header that lists the next object in the sequence. Akamai can read this information and prefetch this object. This scheme relies on assistance from your “intelligent” origin to trigger prefetching. Requirements and setup of an origin are explained in the Akamai Cloud Embed - Implementation Guide. |
content-compression
Include this behavior to provide compression settings. You can enable gzip compression, decompress objects before delivering them to the client, or maintain the origin’s compression settings.
Download schema:
content-compression-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-refresh",
"type": "date-time",
"value": "2018-12-31T11:59:59Z",
"params": {
"mustRevalidate": true
}
}
]
}
content-compression members
Member | Type | Required | Description |
---|---|---|---|
content-compression : Include this behavior to provide compression settings. You can enable gzip compression, decompress objects before delivering them to the client, or maintain the origin’s compression settings. |
|||
name |
Enumeration | ✓ | Enter content-compression to enable this behavior. |
type |
Enumeration | ✓ | Select the appropriate compression setting for this behavior. Use always to compress all objects served to clients that send an Accept-Encoding:*gzip* header, never to decompress objects served to the client, and follow-origin to retain the origin’s compression settings. |
value |
String | ✓ | Enter the MIME types to compress, separated by spaces. The maximum string length is 1024 characters, and wildcards can be used (* ). Enter - if you do not want to apply compression to any MIME type. |
content-refresh
Include this behavior to invalidate the CDN cache at an explicit date and time. This behavior uses epoch time to denote when a request should receive a new copy of the object or a newly validated one.
Download schema:
content-refresh-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "content-refresh",
"type": "epoch",
"value": "1543273814",
"params": {
"mustRevalidate": true
}
}
]
}
content-refresh members
Member | Type | Required | Description |
---|---|---|---|
content-refresh : Include this behavior to invalidate the CDN cache at an explicit date and time. This behavior uses epoch time to denote when a request should receive a new copy of the object or a newly validated one. |
|||
name |
Enumeration | ✓ | Enter content-refresh to invalidate CDN cache at an explicit date/time. |
params |
content-refresh. |
○ | Settings used by this behavior to reapply validation to content. |
type |
Enumeration | ✓ | Declares the format of the value element. Enter epoch to use epoch time; date-time to use an ISO 8601 time value (YYYY-MM-DDThh:mm:ssZ ); date to use an ISO 8601 date value (YYYY-MM-DD ), which invalidates cache at midnight GMT on the specified date; and natural to invalidate content immediately upon publication of the content policy. |
value |
String | ✓ | The time after which the invalidation of objects in cache should occur. |
content-refresh.params : Settings used by this behavior to reapply validation to content. |
|||
mustRevalidate |
Boolean | ○ | If true , the edge server only serves content from cache if it has been validated again after the given invalidation time. If false , the edge server may serve content from cache if an attempt to validate the content again fails to receive a response from the origin server. |
downstream-caching
Include this behavior to control downstream caching of alternate content. Only use this behavior if site failover is enabled for the alternate hostname property. If you do not include this behavior, your subcustomer policy uses the downstream caching settings specified in the alternate hostname property. To enable site failover, use the Subcustomer Enablement behavior in Property Manager.
Download schema:
downstream-caching-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "downstream-caching",
"value": "no-store"
}
]
}
downstream-caching members
Member | Type | Required | Description |
---|---|---|---|
downstream-caching : Include this behavior to control downstream caching of alternate content. Only use this behavior if site failover is enabled for the alternate hostname property. If you do not include this behavior, your subcustomer policy uses the downstream caching settings specified in the alternate hostname property. To enable site failover, use the Subcustomer Enablement behavior in Property Manager. |
|||
name |
Enumeration | ✓ | Enter downstream-caching to control downstream caching of alternate content. |
value |
Enumeration | ✓ | Enter no-store to serve the alternate response with an HTTP Cache-Control: no-store header. Enter no-cache to serve the alternate response with an HTTP Cache-Control: no-cache header. |
geo-blacklist
Include this behavior to block (“blacklist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are allowed.
Download schema:
geo-blacklist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "geo-blacklist",
"type": "region",
"value": "US:CA US:OR US:WA US:ID US:AZ US:NV"
}
]
}
geo-blacklist members
Member | Type | Required | Description |
---|---|---|---|
geo-blacklist : Include this behavior to block (“blacklist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are allowed. |
|||
name |
Enumeration | ✓ | Enter geo-blacklist to block access to content based on the geographic location of the requesting IP address. |
type |
Enumeration | ✓ | Declares the type of geographies to blacklist. Valid types are continent , country , region , and dma . |
value |
String | ✓ | Enter a space-separated list of geographic areas to blacklist. Proper values for these areas are maintained in the EdgeScape Data Codes lists on Akamai Control Center. Each continent and country follows a two-digit format. If matching on region values, these follow a country:region format like US:AK (Alaska in the United States). If matching on dma , enter the integer that represents the Designated Market Area (DMA). Larger areas are include smaller ones, so if you include NA (North America) as a continent, you don’t need to include US as a country. |
geo-whitelist
Include this behavior to allow (“whitelist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are denied.
Download schema:
geo-whitelist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "geo-whitelist",
"type": "country",
"value": "US:CA US:OR US:WA US:ID US:AZ US:NV"
}
]
}
geo-whitelist members
Member | Type | Required | Description |
---|---|---|---|
geo-whitelist : Include this behavior to allow (“whitelist”) access to content based on the continent, country, region/state, or designated marketing area (DMA) of the requesting IP address. (DMA only applies in the United States.) All other geographic areas are denied. |
|||
name |
Enumeration | ✓ | Enter geo-whitelist to allow access to content based on the geographic location of the requesting IP address. |
type |
Enumeration | ✓ | Declares the type of geographies to whitelist. Valid types include: continent , country , region , and dma . |
value |
String | ✓ | Enter a space-separated list of geographic areas to whitelist. Proper values for these areas are maintained in the EdgeScape Data Codes lists on Control Center. Each continent and country follows a two-digit format. If matching on region values, these follow a country:region format like US:AK (Alaska in the United States). If matching on dma , enter the integer that represents the Designated Market Area (DMA). Larger areas are inclusive of smaller ones, so if you include NA (North America) as a continent, you don’t need to include US as a country. |
ip-blacklist
Include this behavior to block (“blacklist”) access based on the requesting IP address. All other requesting IP addresses are allowed access.
Download schema:
ip-blacklist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "ip-blacklist",
"value": "10.10.1.100 10.10.2.100 10.10.3.100"
}
]
}
ip-blacklist members
Member | Type | Required | Description |
---|---|---|---|
ip-blacklist : Include this behavior to block (“blacklist”) access based on the requesting IP address. All other requesting IP addresses are allowed access. |
|||
name |
Enumeration | ✓ | Enter ip-blacklist to block access based on the requesting IP address. |
value |
String | ✓ | Enter a space-separated list of IP addresses or CIDR blocks to deny. All other IP addresses are allowed. |
ip-whitelist
Include this behavior to allow (“whitelist”) access based on the requesting IP address. Only the IP addresses listed are allowed access.
Download schema:
ip-whitelist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "ip-whitelist",
"value": "10.10.1.100 10.10.2.100 10.10.3.100"
}
]
}
ip-whitelist members
Member | Type | Required | Description |
---|---|---|---|
ip-whitelist : Include this behavior to allow (“whitelist”) access based on the requesting IP address. Only the IP addresses listed are allowed access. |
|||
name |
Enumeration | ✓ | Enter ip-whitelist to allow access based on the requesting IP address. |
value |
String | ✓ | Enter a space-separated list of IP addresses or CIDR blocks to allow. All other IP addresses are blocked. |
modify-outgoing-request-header
Include this behavior to modify the outgoing request headers sent from Akamai to an origin. This also works on request headers sent from a client if the request is sent back to the origin, but not a cache hit.
Download schema:
modify-outgoing-request-header-behavior.json
Sample of this behavior in a policy to append the header values, add_this_value
and also_add_this_value
to the outgoing request header, header1
; append add_this_value
to the outgoing request header, header2
; and set a comma plus a space (,
) as the delimiter:
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-request-header",
"type": "append",
"value": "-",
"params": {
"headerList": [
{
"header1": "add_this_value, also_add_this_value"
},
{
"header2": "add_this_value"
}
],
"delimiter": ", "
}
}
]
}
Sample of this behavior in a policy to delete the header values, this_is_an_old_value
and this_is_an_older_value
from the outgoing request header, header1
; delete the empty header, header2
; and set the semicolon and a space (;
) set as a delimiter:
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-request-header",
"type": "delete",
"value": "-",
"params": {
"headerList": [
{
"header1": "this_is_an_old_value; this_is_an_older_value"
},
{
"header2": ""
}
],
"delimiter": "; "
}
}
]
}
Sample of this behavior in a policy to match the header, header1
and overwrite its header value with replace_with_this_new_header_value
(with no delimiter
, because an overwrite
doesn’t use one):
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-request-header",
"type": "overwrite",
"value": "-",
"params": {
"headerList": [
{
"header1": "replace_with_this_new_header_value"
}
]
}
}
]
}
modify-outgoing-request-header members
Member | Type | Required | Description |
---|---|---|---|
modify-outgoing-request-header : Include this behavior to modify the outgoing request headers sent from Akamai to an origin. This also works on request headers sent from a client if the request is sent back to the origin, but not a cache hit. |
|||
name |
Enumeration | ✓ | Set to modify-outgoing-request-header to modify an outgoing request header. |
params |
modify-outgoing-request-header. |
✓ | Use these members to provide attributes to modify outgoing request headers. |
type |
Enumeration | ✓ | Specifies the type of modification to perform if the request meets the criteria set in the rule’s match. Set this to append to add a given header value to a header name set in the headerList . Set this to delete to remove a given header value from a header name set in the headerList . Set this to overwrite to match on a specified header name and replace its existing header value with a new one you specify. Caveats apply to each type . |
value |
String | ✓ | This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (- ). |
modify-outgoing-request-header.params : Use these members to provide attributes to modify outgoing request headers. |
|||
delimiter |
Enumeration | ○ | Specifies the delimiter to be used when indicating multiple values for a header. Set this to a <space> , , (comma), ; (semicolon), ,<space> (comma and space), or ;<space> (semicolon and space). Delimiters are only supported for use with append and delete . Caveats apply to delimiter use. This defaults to a , if nothing is set. |
headerList |
Array | ✓ | A collection of key value pairs that specify the headers and associated values to be modified. The key sets the header name to be modified and the value is the header value to be appended, deleted or overwritten. Various caveats apply to header names and values. |
Usage caveats
Consider the following usage caveats before applying this behavior.
You can modify a maximum of 15 request headers with this behavior, in a single policy.
You can use each behavior
type
(append
,delete
, andoverwrite
) once in a single rule.You can’t modify the same header more than once in a single policy.
You can use multiple
modify-outgoing-request-header
behaviors in the same rule. Ensure they don’t conflict, based on other caveats in this list. (This only applies to this behavior.)You can’t use a CRLF or a colon in header names or header values.
The
append
andoverwrite
behavior types create a non-existent header and apply the specified header value.The
append
behavior type won’t append a header value if it already exists in the header. If duplicate instances of a header value are identified, they are left as is because theappend
type only adds content, it does not remove anything. Use theoverwrite
type in this scenario to completely replace the header content, and remove duplicate values.If multiple occurrences of a single header are included in a request, an
append
ordelete
behavior type only applies to the first occurrence. That header is modified and sent to the origin, and all other instances of the same header in the request are ignored. If you don’t include themodify-outgoing-request-header
, all occurrences of a request header are sent to the origin.The
delete
behavior type can be used to remove an empty header. (If it has no header value.) Just include the header name, and leave the header value empty (for example,"my_header": ""
).The
delete
behavior type only removes a value from a header if that value is found. If the value isn’t found, it does nothing.If the
delete
behavior type removes the only header value, older origin servers may experience issues. (This can result in a “null pointer exception” on an older origin server not built to handle empty headers.)When delimiter-separating multiple header values in a
delete
, values are deleted only if they exist in the order specified. For example, if the policy is set to match and delete"header1": "value1,value3"
, and the actual request header is"header1: value1,value2,value3"
, nothing is deleted, because the exact match,"value1,value3"
wasn’t found. However, if the actual request header is"header1: value2,value1,value3"
,value1
andvalue3
are deleted because they match the order set.The
overwrite
behavior type overwrites all header value information for a header name it matches.If you don’t include the
delimiter
object, it defaults to a comma.If you use a delimiter to include a list of header values, it must match what’s set for the
delimiter
member (or a comma if you didn’t set one.) Otherwise, the API matches on exactly what’s set.If you include a
delimiter
when using theoverwrite
behavior type, Akamai Cloud Embed ignores it.Header names are case-insensitive when matching eligible headers, for all behavior types.
Header values are case-sensitive when matching eligible headers for
append
anddelete
. (Header values are replaced foroverwrite
, so no matching is performed.)Since header names are case-insensitive, the header name you set in a policy is what’s used as the header name once modified.
Blacklisted Request Headers
These headers can’t be modified. If the type
criteria set matches one of these
headers, an error is revealed. Both header names and values are case-insensitive
when matching on blacklisted headers. The *
represents a wildcard.
Connection
Content-Length
Forwarded
Host
TE
Upgrade
x-akamai*
x-cache*
Blacklisted header values
You can’t modify these items in a header value.
akamai-x-*
Known Issue: Appending multiple header values and duplicate, existing values
When you use the append
behavior type and include multiple header values, if a
header value already exists, this behavior duplicates it in the resulting header.
For example, assume you have the existing header, "header1": "value1;value2"
and you set this behavior to append: "header1": "value1;value3;value4"
. This
results in "header1: value1;value2;value1;value3;value4"
. This is because the API
is trying to match on the full value you’ve specified, "value1;value3;value4"
when checking for duplicates.
As a best practice, you should only include multiple header values for an append
if you’re sure one of those values doesn’t already exist.
modify-outgoing-request-path
Include this behavior to provide options for altering the request URL before it is sent to origin.
Download schema:
modify-outgoing-request-path-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-request-path",
"type": "replace",
"value": "/dir1/dir2/###/dir4/"
}
]
}
modify-outgoing-request-path members
Member | Type | Required | Description |
---|---|---|---|
modify-outgoing-request-path : Include this behavior to provide options for altering the request URL before it is sent to origin. |
|||
name |
Enumeration | ✓ | Enter modify-outgoing-request-path to alter the request URL before it is sent to origin. |
type |
Enumeration | ✓ | Set the type of request path change to use. Enter remove to remove the first occurrence of the value from the outgoing request URL; replace-all to replace the original request path before the filename with the path specified in value ; or replace to search for a portion of the original request URL and replace it with a value you define. |
value |
String | ✓ | If using remove , enter the string of characters to remove from the forward request. The behavior doesn’t remove leading and trailing slashes. If using replace-all , enter the URL path to replace the original incoming URL path. If using replace , enter a value in this format: /find/path/###/replace/ path/ , where ### separates the string to find and the string to replace. For example, if your base URL is www.example.com/dir1/dir2/dir3/index.html and you enter /dir1/dir2/###/dir4/ as the value , the resulting URL is www.example.com/dir4/dir3/index.html . |
modify-outgoing-response-header
Include this behavior to modify the outgoing response headers sent from the Edge server back to the client.
Download schema:
modify-outgoing-response-header-behavior.json
Sample of this behavior in a policy to append the header value, new_value1
to the outgoing response header, header1
; append the values newer_value1
and newest_value1
to the outgoing response header, header2
; and set the semicolon (;
) as the delimiter
:
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-response-header",
"type": "append",
"value": "-",
"params": {
"headerList": [
{
"header1": "new_value1"
},
{
"header2": "newer_value1;newest_value1"
}
],
"delimiter": ";"
}
}
]
}
Sample of this behavior in a policy to delete the empty header, header1
; and delete the header values, old_value
, older_value
, and oldest_value
from the outgoing response header, header2
(The behavior only deletes these values if they exist in header2
in the order specified. See Usage caveats):
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-response-header",
"type": "delete",
"value": "-",
"params": {
"headerList": [
{
"header1": ""
},
{
"header2": "old_value,older_value,oldest_value"
}
],
"delimiter": ","
}
}
]
}
Sample of this behavior in a policy to match the header, header1
and overwrite its header value with use_this_instead
(with no delimiter
, because an overwrite
doesn’t use one):
{
"matches": [],
"behaviors": [
{
"name": "modify-outgoing-response-header",
"type": "overwrite",
"value": "-",
"params": {
"headerList": [
{
"header1": "use_this_instead"
}
]
}
}
]
}
modify-outgoing-response-header members
Member | Type | Required | Description |
---|---|---|---|
modify-outgoing-response-header : Include this behavior to modify the outgoing response headers sent from the Edge server back to the client. |
|||
name |
Enumeration | ✓ | Set to modify-outgoing-response-header to modify an outgoing response header. |
params |
modify-outgoing-response-header. |
✓ | Use these members to provide attributes to modify outgoing response headers. |
type |
Enumeration | ✓ | Specifies the type of modification to perform if the response meets the criteria set in the rule’s match. Set this to append to add a given header value to a header name set in the headerList . Set this to delete to remove a given header value from a header name set in the headerList . Set this to overwrite to match on a specified header name and replace its existing header value with a new one you specify. Caveats apply to each type . |
value |
String | ✓ | This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (- ). |
modify-outgoing-response-header.params : Use these members to provide attributes to modify outgoing response headers. |
|||
delimiter |
Enumeration | ○ | Specifies the delimiter to be used when indicating multiple values for a header. Set this to a <space> , , (comma), ; (semicolon), ,<space> (comma and space), or ;<space> (semicolon and space). Delimiters are only supported for use with append and delete . Caveats apply to delimiter use. This defaults to a , if nothing is set. |
headerList |
Array | ✓ | A collection of key value pairs that specify the headers and associated values to be modified. The key sets the header name to be modified and the value is the header value to be appended, deleted or overwritten. Various caveats apply to header names and values. |
Usage caveats
Consider the following usage caveats before applying this behavior.
You can modify a maximum of 15 response headers with this behavior, in a single policy.
You can use each behavior
type
(append
,delete
, andoverwrite
) once in a single rule.You can’t modify the same header more than once in a single policy.
You can’t use a CRLF or a colon in header names or header values.
The
append
andoverwrite
behavior types create a non-existent header and apply the specified header value.The
append
behavior type won’t append a header value if it already exists in the header. If duplicate instances of a header value are identified, they are left as is because theappend
type only adds content, it does not remove anything. Use theoverwrite
type in this scenario to completely replace the header content, and remove duplicate values.If multiple occurrences of a single header are included in a request, an
append
ordelete
behavior type only applies to the first occurrence. That header is modified and sent to the origin, and all other instances of the same header in the request are ignored. If you don’t include themodify-outgoing-response-header
, all occurrences of a request header are sent to the origin.The
delete
behavior type can be used to remove an empty header. (If it has no header value.) Just include the header name, and leave the header value empty (for example,"my_header": ""
)The
delete
behavior type only removes a value from a header if that value is found. If the value isn’t found, it does nothing.If the
delete
behavior type removes the only header value, older origin servers may experience issues. (This can result in a “null pointer exception” on an older origin server not built to handle empty headers.)When delimiter-separating multiple header values in a
delete
, values are deleted only if they exist in the order specified. For example, if the policy is set to match and delete"header1": "value1,value3"
, and the actual request header is"header1: value1,value2,value3"
, nothing is deleted, because the exact match,"value1,value3"
wasn’t found. However, if the actual request header is"header1: value2,value1,value3"
,value1
andvalue3
are deleted because they match the order set.The
overwrite
behavior overwrites all header value information for a header name it matches.If you don’t include the
delimiter
object, it defaults to a comma.If you use a delimiter to include a list of header values, it must match what’s set for the
delimiter
member (or you must use commas if you didn’t set one.) Otherwise, the API matches on exactly what’s set.If you include a
delimiter
when using theoverwrite
behavior type, Akamai Cloud Embed ignores it.Header names are case-insensitive when matching eligible headers, for all behavior types.
Header values are case-sensitive when matching eligible headers for
append
anddelete
. (Header values are replaced foroverwrite
, so no matching is performed.)Since header names are case-insensitive, the header name you set in a policy is what’s used as the header name once modified.
Blacklisted Response Headers
These headers can’t be modified. If the type
criteria set matches one of these
headers, an error is revealed. Both header names and values are case-insensitive
when matching on blacklisted headers. The *
represents a wildcard.
Age
Alt-Svc
Connection
Content-Encoding
Content-Length
Content-Range
Transfer-Encoding
Vary
x-akamai*
x-cache*
Blacklisted header values
You can’t modify the following items when they occur in a header value.
akamai-x-*
Known Issue: Appending multiple header values and duplicate, existing values
When you use the append
behavior type and include multiple header values, if a
header value already exists, this behavior duplicates it in the resulting header.
For example, assume you have the existing header, "header1": "value1;value2"
and you set this behavior to append: "header1": "value1;value3;value4"
. This
results in "header1: value1;value2;value1;value3;value4"
. This is because the API
is trying to match on the full value you’ve specified, "value1;value3;value4"
when checking for duplicates.
As a best practice, you should only include multiple header values for an append
if you’re sure one of those values doesn’t already exist.
origin
Include this behavior to provide origin settings for the specific subcustomer. You need to include: origin DNS hostname, forward host
header, and cache key. Optional settings include the origin base path and ports.
Download schema:
origin-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "origin",
"value": "-",
"params": {
"digitalProperty": "www.mysite.com",
"originDomain": "c1234567.cloudprovider.com",
"cacheKeyType": "origin",
"cacheKeyValue": "-",
"hostHeaderType": "digital_property",
"hostHeaderValue": "-"
}
}
]
}
origin members
Member | Type | Required | Description |
---|---|---|---|
origin : Include this behavior to provide origin settings for the specific subcustomer. You need to include: origin DNS hostname, forward host header, and cache key. Optional settings include the origin base path and ports. |
|||
name |
Enumeration | ○ | Enter origin to set up the origin behavior. Akamai Cloud Embed requires an origin in every content policy. |
params |
origin. |
○ | Origin settings for the policy. |
value |
String | ○ | Enter a dash (- ) for this parameter. |
origin.params : Origin settings for the policy. |
|||
cacheKeyType |
Enumeration | ○ | Enter the method to use when constructing the cache key. Use digital_property if the response is different for each property, origin if the origin response is the same regardless of property, or fixed to set a specific cache key value. |
cacheKeyValue |
String | ○ | If cacheKeyType is fixed , enter a valid domain name for the hostname portion of the cache key. Use a dash (- ) to indicate no value. |
digitalProperty |
String | ○ | Enter the hostname used by the client to access the site or application. Use a valid domain name like www.example.com or blogs.example.com . |
hostHeaderType |
Enumeration | ○ | For requests sent to this origin, enter the host header value to generate. Use digital_property to have the host header match the digital property, origin to use the originDomain value as the host header, and fixed to use the hostHeaderValue as the host header. |
hostHeaderValue |
String | ○ | If hostHeaderType is fixed enter a valid domain name to use in the host header. Use a dash (- ) to indicate no value. |
originDomain |
String | ○ | Enter the origin hostname you provide to subcustomers when you provision services. Your entry can either be a valid domain name or an IP address. |
origin-characteristics
Include this behavior if you have Integrated Cloud Acceleration (ICA), to select the type of origin supporting your Akamai Cloud Embed implementation. Use the origin
behavior to configure origin settings for your subcustomers at the policy level.
Download schema:
origin-characteristics-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "origin-characteristics",
"value": "azure"
}
]
}
origin-characteristics members
Member | Type | Required | Description |
---|---|---|---|
origin-characteristics : Include this behavior if you have Integrated Cloud Acceleration (ICA), to select the type of origin supporting your Akamai Cloud Embed implementation. Use the origin behavior to configure origin settings for your subcustomers at the policy level. |
|||
name |
Enumeration | ✓ | Use the origin-characteristics behavior to select the type of origin you are using for your Akamai Cloud Embed implementation. |
type |
Enumeration | ✓ | The type of origin supporting your implementation. Enter azure if you use an Azure Media Services live origin. Use unknown for all other origins. |
origin-failover
This feature identifies primary origin connection failures based on a type you specify and marks that origin as “bad” after connections to all its IPs fail repeatedly. Rather than issuing a redirect to the end user, requests are failed over to a backup origin you call out. This improves response times, because the end user doesn’t have to wait several seconds for a connect-timeout on the forward request. Additionally, you specify a duration of time the primary origin is marked as bad. During this time, all requests are failed over to your backup origin. This relieves pressure on the primary by reducing the number of connection attempts, at a time when it appears to be having difficulties.
Download schema:
origin-failover-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "origin-failover",
"type": "backupOrigin",
"value": "-",
"params": {
"errorType": "timeout",
"originConnectionTimeout": "20s",
"errorCountBeforeFailover": 10,
"timeoutErrorCacheDuration": "2h",
"backupOrigin": "backup.myorigin.com",
"customForwardHost": "somebackuporigin.com"
}
}
]
}
origin-failover members
Member | Type | Required | Description |
---|---|---|---|
origin-failover : This feature identifies primary origin connection failures based on a type you specify and marks that origin as “bad” after connections to all its IPs fail repeatedly. Rather than issuing a redirect to the end user, requests are failed over to a backup origin you call out. This improves response times, because the end user doesn’t have to wait several seconds for a connect-timeout on the forward request. Additionally, you specify a duration of time the primary origin is marked as bad. During this time, all requests are failed over to your backup origin. This relieves pressure on the primary by reducing the number of connection attempts, at a time when it appears to be having difficulties. |
|||
name |
Enumeration | ✓ | Set to origin-failover to add this to your policy to configure offload of failover detection and recovery. |
params |
origin-failover. |
✓ | These parameters are used to define your backup origin as well as what’s used to mark an origin as bad, in order to failover requests to that backup origin. |
type |
String | ✓ | Specifies the type of failover to use if the request meets the criteria set in the rule’s match. Set this to backupOrigin to failover to a backup origin. |
value |
String | ✓ | This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (- ). |
origin-failover.params : These parameters are used to define your backup origin as well as what’s used to mark an origin as bad, in order to failover requests to that backup origin. |
|||
backupOrigin |
String | ✓ | The domain name (the complete path and hostname) or IP address of the origin serving as your backup for failover. |
custom |
String | ○ | Include this to customize what’s included in the X-Forwarded-Host header, when a failover directs the request to a backupOrigin . (This header typically identifies the original host requested by the client in the Host HTTP request header.) |
error |
Integer | ○ | This tells Akamai how many errors of the selected errorType , timeout to recognize before an origin is considered bad, and failover is applied. As a best practice, set this to a value higher than 1 . An origin shouldn’t be considered bad after only a single failure. Note that the default for this is 0 . So, if you don’t set a value, all error requests are failed over and the first failed request marks the origin as bad. There are additional caveats that apply to this member, specifically when a request is actually failed over. |
errorType |
Enumeration | ✓ | This defines the type of error that occurs to mark the connection as a failure. Set this to timeout to indicate a failure once an origin connection request times out after a specific amount of time. Caveats apply to the use of timeout . (Currently, only timeout is supported. You can expect additional errorType values with a future release.) |
origin |
String | ○ | The amount of time that constitutes an origin connection timeout and results in a failure. If you leave this parameter out, the connection timeout is default set to five seconds. |
timeout |
String | ○ | Set an amount of time that needs to pass before a request retries an origin IP that was flagged as bad, as a result of a timeout error. |
Usage caveats
Consider the following usage caveats before applying this behavior.
Failover to your specified
backupOrigin
happens under two conditions: when atimeout
request error occurs; or when an origin receives a request after ACE has marked it as bad,because theerrorCountBeforeFailover
count has been reached. (Eachtimeout
request error counts toward this total.) Marking an origin as bad stops connection attempts to it while it may be having trouble.This behavior has two primary functions: To failover error requests to a
backupOrigin
you specify, and to mark an origin as “bad” after a certain number of these error requests occur, to stop further requests to a potentially origin when it may be having trouble.The Akamai server tries a failed connection one more time before counting it towards your
errorCountBeforeFailover
.The
errorCountBeforeFailover
member marks an origin as bad for the request that occurs after the quantity you’ve specified, and enacts thetimeoutErrorCacheDuration
to stop requests from targeting the origin for that length of time. Each subsequent request is then failed over to thebackupOrigin
. For example, if you set this to six, the seventh failed request triggers thetimeoutErrorCacheDuration
and the eighth and subsequent requests are failed over to yourbackupOrigin
.When used with the Origin behavior in a policy, set its
cacheKeyType
member toorigin
. This keeps cache key creation for your primary origin consistent with the Origin Failover behavior cache key creation for your backup origin.During failover to your backup origin, the cache key is modified by adding a “
b-
” in the path. This avoids cache sharing and negative Time to Live (TTL) settings that may use what is in cache instead of accessing your specified backup origin. For example, assume a request is sent to this origin that has been as marked as bad:/prodtest-ff.qa.akamai.com.partnerdomain.net/OD/bird.jpg
The request is rerouted to this backup origin andb-
is added to the origin hostname:/b-mde-origin.qa.akamai.com.partnerdomain.net/OD/bird.jpg
Duration values allow for settings in days (d), hours (h), minutes (m), seconds (s), and milliseconds (ms). All default values are applied in seconds.
If you’ve enabled Tiered Distribution in your base configuration, origin failover is only valid for the top-tier level. (This represents the “last hop” to your origin to request content.)
referer-blacklist
Include this behavior to block (“blacklist”) access based on the Referer
request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served by Akamai Cloud Embed from a domain trusted by the content owner.
Download schema:
referer-blacklist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "referer-blacklist",
"value": "/dir1/dir2/###/dir4/"
}
]
}
referer-blacklist members
Member | Type | Required | Description |
---|---|---|---|
referer-blacklist : Include this behavior to block (“blacklist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served by Akamai Cloud Embed from a domain trusted by the content owner. |
|||
name |
Enumeration | ✓ | Enter referer-blacklist to block access based on the Referer request header. |
value |
String | ✓ | Enter a space-separated list of Referer header values to disallow. Use the * wildcard to match on a substring within the header value. |
referer-whitelist
Include this behavior to allow (“whitelist”) access based on the Referer
request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner.
Download schema:
referer-whitelist-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "referer-whitelist",
"value": "www.mysite.com www.myothersite.com*"
}
]
}
referer-whitelist members
Member | Type | Required | Description |
---|---|---|---|
referer-whitelist : Include this behavior to allow (“whitelist”) access based on the Referer request header. This behavior helps verify that the client is a browser that supports RFC 2616, section 14.36, and that the referring HTML page is served from a domain trusted by the content owner. |
|||
name |
Enumeration | ✓ | Enter referer-whitelist to allow access based on the Referer request header. |
value |
String | ✓ | Enter a space-separated list of Referer header values to allow. Use the * wildcard to match on a substring within the header value. |
site-failover
Include this behavior to define the alternate hostname and path to use when the edge server can’t contact the origin server.
Download schema:
site-failover-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "site-failover",
"type": "serve-301",
"params": {
"httpResponseStatus": "404 500:504",
"alternateHostname": "www.mysite_failover.com",
"alternatePath": "/failover/mysite",
"preserveQueryString": true
}
}
]
}
site-failover members
Member | Type | Required | Description |
---|---|---|---|
site-failover : Include this behavior to define the alternate hostname and path to use when the edge server can’t contact the origin server. |
|||
name |
Enumeration | ✓ | Enter site-failover to define an alternate response to serve when the edge server can’t contact the origin server. |
params |
site-failover. |
○ | These are failover settings. |
type |
Enumeration | ✓ | Select the failover action to use. Enter serve-301 for 301 redirects, serve-302 for 302 redirects, or serve-alternate to send a request to an alternate hostname and path. |
site-failover.params : These are failover settings. |
|||
alternate |
String | ○ | Enter the domain of the hostname to failover to. Enter a dash (- ) to use the original hostname when constructing the new URL. |
alternatePath |
String | ○ | Enter a valid URI path to failover to. Always include the initial slash. Include the closing slash to change the URL path but keep the original filename. Enter a dash (- ) to use the original path when constructing the new URL. |
http |
String | ○ | Enter a space-separated list of the HTTP status codes served to the client when site-failover is not in effect. You can use integer ranges (for example, 404 , 500:504 ). |
preserve |
Boolean | ○ | Enter true to retain the query string from the original request URL, or enter false to remove the query string. |
token-auth
Include this behavior to use tokens to control access to content. You can choose to transmit the token in a cookie, header, or query parameter.
Download schema:
token-auth-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "token-auth",
"value": "-",
"type": "serve-301",
"params": {
"tokenName": "__mytoken__",
"tokenDelimiter": "~",
"aclDelimiter": "!",
"hmacAlgorithm": "SHA256",
"escapeTokenInputs": true,
"ignoreQueryString": false,
"key": "adf123",
"transitionKey": "bce987",
"salt": "worldnews175892"
}
}
]
}
token-auth members
Member | Type | Required | Description |
---|---|---|---|
token-auth : Include this behavior to use tokens to control access to content. You can choose to transmit the token in a cookie, header, or query parameter. |
|||
name |
Enumeration | ✓ | Set to token-auth to use tokens to control access to content. |
params |
token-auth. |
○ | Use these parameters to define how tokens are used by this behavior. |
value |
String | ○ | This is ignored for this match type, but required for consistency in the API. Set the value to a dash (- ). |
token-auth.params : Use these parameters to define how tokens are used by this behavior. |
|||
aclDelimiter |
String | ○ | Specifies a single character to separate access control list (ACL) fields. You can’t use alphanumeric characters, or any of the following character class: [.&`=/:%] . If you don’t specify a value, ! is used as the delimiter. |
escape |
Boolean | ○ | Set to true input values are escaped before adding them to the token. |
hmacAlgorithm |
Enumeration | ○ | Specifies the algorithm to use for the token’s hash-based message authentication code (HMAC) field. Valid entries are SHA256 , SHA1 , or MD5 . |
ignore |
Boolean | ○ | Set to true query strings are removed from a URL when computing the token’s HMAC algorithm. |
key |
String | ○ | Specifies an even number of hex digits for the token key. An entry can be up to 64 characters in length. |
salt |
String | ○ | Specifies a salt for use in the token. This can be a maximum of 250 characters, and it can’t use characters from the following class: [~@#%^&=/|\] . |
tokenDelimiter |
String | ○ | Specifies a single character to separate the individual token fields. You can’t use characters from the following class: [a-zA-Z0-9=&/\:%] . If you don’t specify a value, ~ is used as the delimiter. |
tokenName |
String | ○ | Specifies the name of the token. Match the string on the following regular expression: ^([a-zA-Z_][a-zA-Z0-9-_]*)$ . |
transitionKey |
String | ○ | Specifies an even number of hex digits for the token transition key. An entry can be up to 64 characters in length. |
url-redirect
Include this behavior to configure redirect responses for specific client requests, and stop them from contacting the origin.
Download schema:
url-redirect-behavior.json
Sample inclusion for this behavior in a PUT policy operation:
{
"matches": [],
"behaviors": [
{
"name": "url-redirect",
"type": "301",
"value": "-",
"params": {
"protocol": "request",
"hostname": "request",
"staticHostname": "www.somedomain.com",
"subDomain": "music",
"path": "request",
"staticPath": "/abc",
"pathPrefix": "/pre",
"pathSuffix": "/su",
"includeQueryString": true
}
}
]
}
url-redirect members
Member | Type | Required | Description |
---|---|---|---|
url-redirect : Include this behavior to configure redirect responses for specific client requests, and stop them from contacting the origin. |
|||
name |
Enumeration | ✓ | Set url-redirect to define the URL used for a redirect client request. |
params |
url-redirect. |
✓ | These members are used to customize the URL used for the redirect. |
type |
Integer | ✓ | Specifies the type of redirect sent to the client if the request meets the criteria set in the rule’s match. You can choose from 301 moved permanently, 302 found, 303 see other, or 307 temporary redirect. |
value |
String | ✓ | This is ignored for this behavior, but required for consistency in the API. Set the value to a dash (- ). |
url-redirect.params : These members are used to customize the URL used for the redirect. |
|||
hostname |
Enumeration | ✓ | This defines the destination hostname that should be used in the redirect URL. Allowed values include: static to apply a unique staticPath , addSubDomain to preface the hostname with a subDomain in the redirect request, replaceSubDomain to replace an existing subDomain value with one you specify, or request to use a subdomain already set in the client request. |
include |
Boolean | ○ | When enabled, retains the query string on the redirect request. Defaults to true . |
path |
Enumeration | ✓ | This defines how the redirect URL is constructed. Allowed values include: static to apply a fixed staticPath , addPrefix to preface the path in the client request with a pathPrefix , addSuffix to append a pathSuffix to the path in the client request, or request to only use the path provided in the client request. |
path |
Boolean | ○ | Include if path is set to staticPath . Indicates whether the path also includes the filename and extension for the redirect. Defaults to false . |
pathPrefix |
String | ○ | Include if path is set to addPrefix . Specifies the prefix to add to the path in a redirect request. For example, to redirect from the path /example.html to /baseball/example.html , set this to /baseball . You can’t use a single / to specify this path. A valid path is a / followed by at least one character. |
pathSuffix |
String | ○ | Include if path is set to addSuffix . The suffix to be added to the path in a redirect request. For example, to redirect from the path /example/index.html to /example/football/index.html , set this to /football . You can’t use a single / to specify this path. A valid path is a / followed by at least one character. |
protocol |
Enumeration | ✓ | This defines the destination protocol to be used for the redirect URL. Allowed values include: HTTP to set the request to non-secure, HTTPS to set it to secure, or request to use the protocol set in the client request. |
staticHostname |
String | ○ | Include if hostname is set to static . Set this to the desired hostname for use in the redirect URL. |
staticPath |
String | ○ | Include if path is set to staticPath . Set this to a static path that should be used in the redirect URL. A valid path is a / followed by at least one character. |
subDomain |
String | ○ | Include if hostname is set to addSubDomain or replaceSubDomain . If set to addSubDomain , specify the subdomain to preface the existing domain. For example, to redirect from example.com to www.m.example.com set this value to www . If set to replaceSubDomain , set a value to replace an existing subdomain. Include a subdomain in the client request hostname, and only the first subdomain is replaced. For example, to change a redirect URL subdomain from domain.example.com or www.example.com to newdomain.example.com , set the value to newdomain . |
Errors
This section shows you how to handle various kinds of errors this API generates, and lists the range of HTTP status codes along with their likely causes.
Error responses
The following example shows an error response for a request processed by this API:
{
"errorCode" : 403,
"message" : "Authorization failed",
"description" : "The user is not authorized by Akamai Cloud Embed to access the policies or subcustomers assigned to the given property id.",
"helpLink" : "https://developer.akamai.com/api/delivery-policies/errors.html#403",
"errorInstanceId" : "31f1a7532f",
}
You would expect to see a message like this if the property ID is not valid or is not configured correctly.
HTTP status codes
This section lists the full range of response codes the API may generate.
Code | Description |
---|---|
200 | The operation was successful. |
201 | Resource successfully created. |
202 | Resource successfully accepted. |
400 | Bad Request. |
401 | Authentication failure. |
403 | Access is forbidden. |
404 | Resource not found. |
408 | Request timeout. |
500 | Internal server error. |
503 | Too many requests. Service is temporarily unavailable. |