Support for large file delivery

You need to run the "Create or update a policy" operation via the ACE API, and set the type element value to large-files in the content-characteristics behavior.

Create or update a policy

General instructions on this operation can be found in the Akamai Cloud Embed API v2 documentation. (See Create or update a policy.)

Define the appropriate match criteria in the delivery policy

Like all other rules in a delivery policy, you must set a match criteria (matches) that must be met to apply the associated behaviors. In the example presented here, the url-wildcard match is used. This match compares the incoming request path (excluding query string) to what is defined as the value for the match "/*" is set here, which indicates all incoming request paths.

Include the "content-characteristics" behavior and set required members

To set up this support, you need to include the content-characteristics behavior, and the following members must be included:

  • type: This must be set to large-files.
  • value: This must be included and always set to a hyphen (-).

Optional parameters

A single parameter ("params") is available for this use case.

Name Type Description
objectSize String (optional) Apply any of the following values:
  • lt1mb: Specifiy this for files less than 1 MB in size. (This is not considered a "large file" use case.)
  • 1mbto10mb: Specify this for files from 1 MB to 10 MB in size. (This is not considered a "large file" use case.)
  • 10mbto100mb: (Default) Specify this for files from 10 MB to 100 MB in size. (This is considered a "large file" use case.)
  • gt100mb: Specify this for files that are 100 MB in size and larger. (This is considered a "large file" use case.)
Note: If you have added the Content Characteristics - Large File behavior to thesubcustomer's base configuration, and set an Origin Object Size, what you set via the objectSize parameter in a policy will override that setting for this specific subcustomer.

You should know subcustomer file size requirements

The params settings, 10mbto100mb and gt100mb are considered "large file" settings. The other settings represent much smaller object sizes, and they actually prevent serving large objects, because the “partial object caching” (POC) feature is disabled with these cases.

POC increases origin server offload by caching in chunks, instead of as a single, composite object. POC is required for the delivery of "large files"—those in excess of 10 MB in size. (It is automatically enabled if you set 10mbto100mb or gt100mb in a policy.) If you set too small a file size, POC will not be enabled for these larger files, and 403 errors will be returned for requests.

Also, if you specify a "large file" setting, but your origin never actually serves files in that size range, the Akamai platform makes additional requests to the origin. (This can impact overall performance and access.) This happens because the Edge server requests the first byte of each object to determine if the minimum object size criteria (at least 10MB) has been met. Once that check fails, the server simply re-requests the entire object from the origin.

We recommend that you verify the size of your delivery objects on your subcustomer's origin, and select the appropriate size to ensure that POC is enabled or disabled, as necessary.

JSON Examples

  • Example 1: This example shows how an endpoint is optimized for large files.
    {
        "rules":[
            {  
                "matches": [
                    {
                        "name": "url-wildcard",
                        "value": "/*"
                    }
                ],
                "behaviors": [
                    {
                        "name": "origin",
                        "value": "-",
                        "params": {
                            "cacheKeyValue": "-",
                            "digitalProperty": "downloadcustomer.partnerdomain.net",
                            "cacheKeyType": "origin",
                            "hostHeaderValue": "-",
                            "originDomain": "downloadcustomer.origin.mediaservices.partnerdomain.net",
                            "hostHeaderType": "origin"
                        },
                    },
                    {
                        "name": "content-characteristics",
                        "type": "large-files",
                        "value": "-",
                        "params": {
                            "objectSize": "gt100mb",
                        }
                    }
                ]
            }
        ]
    }
  • Example 2: The snippet below shows the content-characteristics behavior with an empty params object. In this case, the 10mbto100mb is automatically used as the default. (Objects will be fetched in byte-range specific chunks, using the 10 MB to 100 MB size setting.)
    {
        "name": "content-characteristics",
        "type": "large-files", 
        "value": "-",
        "params":{}
    }