content control interfaces

August 26, 2008

Akamai Content Control InterfacesContent Control Utility (CCU)

Content Control Utility SOAP API (CCUAPI)Enhanced Content Control Utility (ECCU)

ECCU File UploadECCU Publisher (PublishECCU)

Akamai Technologies, Inc.Akamai Customer Care: 1-877-425-2832 or, for routine requests, email [email protected]

Akamai EdgeControl, for customers and resellers: http://control.akamai.com

Akamai Content Control InterfacesCopyright © 2003–2008 Akamai Technologies, Inc. All Rights Reserved.

No part of this publication may be reproduced, transmitted, transcribed, stored in a retrieval system or translated into any language in any form by any means without the written permission of Akamai Technologies, Inc. While every precaution has been taken in the prep-aration of this document, Akamai Technologies, Inc. assumes no responsibility for errors, omissions, or for damages resulting from the use of the information herein. The information in these documents is believed to be accurate as of the date of this publication but is sub-ject to change without notice. The information in this document is subject to the confidentiality provisions of the Terms & Conditions governing your use of Akamai services.

Akamai, EdgeComputing, and EdgeControl are registered service marks of Akamai Technologies, Inc. Other products or corporate names may be trademarks or registered trademarks of other companies and are used only for the explanation and to the owner’s benefit, without intent to infringe or to imply any endorsement of Akamai or its services by, or relationship between Akamai and, the owners of such marks or to imply that Akamai will continue to offer services compatible with technology offered by such owners.

Java is a trademarks or registered trademarks of Sun Microsystems, Inc. in the United States and other countries.

US Headquarters8 Cambridge Center

Cambridge, MA 02142

Tel: 617.444.3000Fax: 617.444.3001

US Toll free 877.4AKAMAI (877.425.2624)

For a list of offices around the world, see: http://www.akamai.com/en/html/about/locations.html

http://control.akamai.com

http://www.akamai.com/en/html/about/locations.html

ContentsCHAPTER 1. INTRODUCTION • 5

About the Content Control Mechanisms . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .5About the CCU and ECCU . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Removal-based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6Invalidation-based . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .6

Best Practices Considerations: Which Interface to Use, and Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . .7CCU Limitations . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .7ECCU Limitations. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8Refresh or Remove by CP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .8Refresh Specific URLs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9Refresh by Directory or Extension . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9Refresh by More Complex Properties . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9Refresh Without Configuration File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .9

A Summary Comparison of the Tools. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .10

CHAPTER 2. CONTENT CONTROL UTILITY • 11Before You Begin. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .11

Using the Content Control Utility . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12Submitting Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .12About the Data Entry and the File Upload . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .13

If You Upload a File. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14If You Purge By CP Code . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .14

On-Screen Submission Confirmation . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .15Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .16

CHAPTER 3. CONTENT CONTROL UTILITY SOAP API • 19Supported Akamai Services . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .19

Using CCUAPI . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Guidelines . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Setup . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Using CCUAPI with Perl . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20

Perl-Specific Prerequisites. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .20Using CCUAPI with Perl. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Using CCUAPI with Visual Basic . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21VB-Specific Prerequisites . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21VB Example . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .21

Using CCUAPI with Java and Axis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .22CCUAPI Reference . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25

Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Function Detail . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .25Function Output. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Sample Output . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .26Result Codes and Troubleshooting . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . .27

Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release. 3

CHAPTER 4. ENHANCED CONTENT CONTROL UTILITY • 29Before You Begin . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29Before You Upload ECCU Files. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 29

Using the ECCU. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 30Viewing Previous Refresh Requests . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32

Resubmitting a Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 32About the Data Fields . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 33ECCU Status Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

Informational Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34Error Messages . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 34

CHAPTER 5. ECCU PUBLISHER (PUBLISHECCU) • 35ECCU Publisher . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 35

CHAPTER 6. ABOUT DIGITAL PROPERTIES • 37The PropertyName, Type, and Exact / Inexact Match. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37

Digital Property Attributes Configured in Setup, Not in These Interfaces . . . . . . . . . . . . . . . . . . . . . . . . 37The Digital Property and the ARL . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 37Exact Match or RHS? . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 38

CHAPTER 7. ENHANCED CCU REQUEST FORMAT • 39Format of an Enhanced CCU Request . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 39

Rules for Proper Syntax . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Revalidation Examples . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40

Based on the Digital Property . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 40Based on Host Header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Based on Directory Structure . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41Based On File Extension. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 41

Best Practices in Requests: Use Space-Separated Values . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 42The Revalidate Tag . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Using Multiple Revalidate Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43About Epoch Time . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 43

Match Tags . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 44Summary of Matches Used to Revalidate Content . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 45Path Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46

recursive-dirs. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 46sub-dirs-only. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 47this-dir . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48filename . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 48

Request Property Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49ext. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49cookie . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 49cpcode-range. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 51arltype. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52request-header. . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 52request-type . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 54method . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55protocol . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55query-string . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 55typecode . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

Response Property Matches . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57response-header . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 57

4 Akamai Content Control Interfaces. Akamai Confidential. NDA Required for Release.

Chapter 1. Introduction

In This Chapter

About the Content Control Mechanisms

This document discusses the content control interfaces, which can be used to refresh Akamai-served content. At Akamai®, the phrase content control refers to the control over the refreshing or removing of objects cached in the Akamai network.

When you serve content through the Akamai network, one significant benefit is the ability to cache content at the “edge” of the internet, that is, near the end user. The normal method to refresh or replace the content is to set a TTL (time-to-live) in cache for objects, which you can set by way of max-age type response headers, by con-figuration files, or by encodings in the ARL (Akamai Resource Locator).

When the TTL expires, an Akamai node receiving a client request checks with the origin using a conditional HTTP GET (also called an If-Modified-Since, or IMS, GET request). If the object has changed, the origin server sends the new version; oth-erwise, the origin sends an HTTP 304 Not Modified response, and Akamai serves the cached instance of the object. Akamai provides numerous options and variations on this scenario, but that is the basic mechanism.

When you need to manually refresh the content and not wait for TTL expiration, Akamai provides two basic mechanisms to meet different needs and preferences, and the basic mechanisms have a variety of interfaces you can use:

• Content Control Utility (CCU)—allows you to specify objects by URL/ARL (Akamai Resource Locator), or by CP Code, to remove from cache and refresh from the origin.

The CCU can be used as a Web interface on Akamai EdgeControl and as a SOAP-based API (CCUAPI).

• Enhanced Content Control Utility (ECCU)—allows you to specify objects to refresh by rules using path and extensions or other, more complex criteria. There are three ways to use ECCU:

- Web interface on Akamai EdgeControl. Using the Web interface, you can specify path and extension rules only.

- File upload, using a function on Akamai EdgeControl. Uploading ECCU files allows you to specify more complex rules by which objects will be

About the Content Control Mechanisms • 5

About the CCU and ECCU • 6

Best Practices Considerations: Which Interface to Use, and Limitations • 7

A Summary Comparison of the Tools • 10


Introduction

refreshed—not only path or extension, but also by the request header or method, protocol, or other criteria.

- ECCU Publisher (PublishECCU) is an EdgeControl Web Service that pro-vides for uploading an ECCU file using a SOAP API, so that you can create a local programmatic interface.

About the CCU and ECCU

Both the CCU and ECCU need to propagate refresh instructions through the Aka-mai network. For CCU this normally takes about 10 minutes; if you submit over 200 ARLs it takes longer to process them all. For ECCU the normal time is 20–40 min-utes; ECCU takes longer than CCU due to a different set of safety checks performed. The differences between the mechanisms, at the basic level, are:

• The CCU and CCUAPI provide for removing and refreshing specific objects, for example, as specified by URL or ARL or all objects under a CP code, using removal-based or invalidation-based refresh. The CCU can handle many thou-sands of requests per day.

• The ECCU provides for invalidation-based refresh by rules such as date/time, path, and extension. The ECCU file upload and PublishECCU provide for invalidation by criteria beyond path and extension such as request header, request method or protocol.

Removal-based Removal-based means that when the Akamai edge server receives a client request, the specified objects are removed from cache and a full GET is sent to the origin to fetch the object and refresh the cache.

Invalidation-based Invalidation-based means that when the edge server receives a client request, it sends an If-Modified-Since, a conditional GET, to the origin. The edge server will remove and replace the cached object only if a newer version is found on the origin.

ECCU Matches and the purge.data File

When you create an ECCU request, the requests add to or replace matches in a purge.data XML file, a file created and maintained for your ECCU matches. The ECCU match refers to the refresh rule you set, for example, /bin/images/*.gif, . The match also includes the revalidate timestamp. Note that the match refers to the rule, not to the files matching the rule. For example, /bin/images/*.gif is a match—not /bin/images/file1.gif, file2.gif, etc.

ECCU matches are applied to every request for that host header, which can impact performance if you have a great many unique matches. Objects are not refreshed at the origin unless the timestamp shows them to be stale, of course.

Your purge.data file persists, and the code lines with the matches persist until they are replaced. Matches are replaced if a the new match includes the old at a parent level. For example, if you previously used /bin/images/*.gif as a match but you are cur-rently submitting a revalidation request that includes /bin/*.*, the latter will replace



the former, assuming the timestamp is for a current date and time. Matches are replaced, or pruned, when there are matches with more recent timestamps.

Since requests persist in the purge.data, the file will grow without bound without maintenance. To prevent growth to a point that damages performance, Akamai prunes requests using a match of /*.* (all directories, all extensions) with a timestamp as distant in the past as possible to slightly reduce file size. Akamai does this automat-ically when the file grows beyond a configurable size, for example, 250KB.

ECCU File Structure and Digital Properties

The ECCU file structure, used in the Enhanced CCU, ECCU file upload, and Pub-lishECCU, is discussed in “Enhanced CCU Request Format” on page 39. The ECCU file is an XML structure that allow you to specify the rules by which content will be refreshed. For PublishECCU and ECCU file upload, you create ECCU files, while in the ECCU you specify the properties in the browser UI but can then view the ECCU structure which is created for you by the Web interface.

When you work with the ECCU structure, you work with digital properties, digital property types, and exact/inexact matches. These are described in “About Digital Properties” on page 37.

Best Practices Considerations: Which Interface to Use, and Limitations

The CCU and CCUAPI applications are best suited to use when you have a set of individual objects whose name (ARL or URL) is known in advance. You can remove many thousands of individual objects using CCU, which efficiently removes the con-tent from the Akamai edge servers in batches. If there are more than about 10,000 objects, you should consider purge by CP code. The ECCU is best used when you need to use rules such as directory or extension or more complex rules.

Whenever you use any content control mechanism, make sure to update the content on your origin server before submitting the request. Refresh instructions reach the edge servers within seconds even though the final confirmation of completion takes minutes to arrive.

General Limitations All the CCU and ECCU applications propagate refresh or removal instructions to every edge server in the Akamai network and await confirmation from all of those servers that the content has been removed or invalidated. These mechanisms are not meant to substitute for using TTL (time-to-live) settings in your configuration or in response headers, which better maximize system and content delivery performance.

Load Spikes When using CCU or ECCU, you need to be aware of the possibility of creating a spike in the load on your origin as many concurrent requests come in for removed or invalidated objects. Full GETs (removal-based) may cause more load than conditional GETs (invalidation-based) unless all objects have changed. A mitigation is to space refresh requests over time—not specifying all objects in one submission

CCU Limitations One limit is that files submitted for CCU requests should contain no more than about 100 URLs of about 400 characters in length. If you receive a “Request Entity Too Large” error, split your file into smaller files and try again."


Introduction

You can submit any number of files containing about 100 URLs, but you should have no more than 10,000 outstanding requests at any one time. If you receive a Code 332 error, which indicates you have exceeded that limit, you should wait about 10 minutes and try again.

The CCU request does not persist—it is executed by the edge server and then “for-gotten.” Any content matching the CCU request is removed one time. If another request comes for the content, a fresh copy will repopulate the cache.

ECCU Limitations Using ECCU applications, Akamai recommends that you limit the number of matches to 250 or fewer—see “ECCU Matches and the purge.data File” on page 6 for a definition of ECCU matches. Submitting more than 250 invalidation requests at one time can result in a “global invalidation” –revalidating all content for that host header. The way to avoid this is to invalidate multiple objects or paths in one request, as described on page 42.

You should avoid matching on content that is unique to a single or few users, and submit no more than 100 requests per day. This recommendation is not an absolute maximum, and more matches or requests on a particular day may be processed with-out incident, but consistently exceeding the recommended limits may result in degraded performance as measured by timely refreshing of the objects.

The purge.data file consumes server memory to read, parse, and hold the resulting parse tree in memory. Thus, a large number of ECCU matches—a large purge.data file—may lead to decreased performance showing as longer service times for your content. It is best to keep purge.data files small. You can occasionally prune your purge.data file with a match of “/*.*” and a timestamp of, for example, two weeks ago to keep the file size down. You’d need to use ECCU file upload or the SOAP API to specify a timestamp other than “now.” The pruning will cause a higher forward request rate for your objects matched by “/*.*” that were not otherwise revalidated, but in practice, this small increase has not been significant enough to cause problems.

Akamai will automatically prune requests using a match of /*.* (all directories, all extensions) with a timestamp as distant in the past as possible to slightly reduce file size, when the purge.data file grows beyond a configurable size (for example, 250KB)

Note that you cannot otherwise delete matches from the purge.data file. The “Delete” instruction in the PublishECCU API does not delete matches from the purge.data file, it removes ECCU requests from view in the Web UI.

Finally, note that the ECCU invalidates content, it does not remove it. If you need to actively remove objects from cache you must use the CCU application.

Corner Cases One “corner case” exists if an object is fetched and cached by way of two different digital properties. Under removal-based refresh, any client request for the object will cause it to be re-fetched.

Under the invalidate-based method, however, a client request for the object that does not match the criteria you set in the ECCU file will not cause it to be refreshed. The



object is refreshed only when a client request occurs that matches the criteria you set in the ECCU file or Enhanced CCU submission.

Refresh or Removeby CP Code

The CCU and CCUAPI applications can remove or invalidate all objects with a given CP code. This is best used when all or almost all objects have been modified. If only some have been modified, you should not use the CP code so the cached object con-tents do not have to be re-fetched from the origin server. When you refresh by CP Code, you need to be aware of the possibility of creating a spike in the load on your origin, as many concurrent requests come in for refreshed objects.

Refresh SpecificURLs

The CCU is best suited for refreshing specific URLs, and it is strongly recommended that you use it rather than ECCU, because of the advantages of speed, the option to directly invalidate, and efficiency on the network.

Refresh by Directoryor Extension

The ECCU is best suited when you can best identify by objects by directory or file extension. The ECCU file upload UI and ECCU Publisher also provide this func-tionality, of course. The ECCU application works best with a few matches that cover broad categories of content. For example, “/images/*.gif ” can easily be invalidated across all edge servers with the ECCU application.

Refresh by MoreComplex Properties

The ECCU file upload and ECCU Publisher provide for invalidation by such criteria as the Request header, Request method or protocol, contents of a query string, and other criteria. See “Enhanced CCU Request Format” on page 39.

Refresh WithoutConfiguration File

ECCU file instructions apply to content configured for control with edge server con-figuration files. If your content does not use a configuration file—for example, some content served through Freeflow or Freeflow Streaming—you must use CCU.


Introduction

A Summary Comparison of the Tools

To summarize the preceding discussion, this table lists the various interfaces that can be used to manually refresh cached content on the Akamai network. The interfaces are listed from top to bottom: the least complex at the top to the most flexible and functional but most complex to use, at the bottom.

If you have further questions about content delivery and invalidation options please contact your Akamai representative or Akamai Customer Care.

Table 1: Comparing and Contrasting Akamai Content Control Tools

Tool Description Advantages Disadvantages

CCUContent Control Utility UI

A control.akamai.com web page that allows you to specify objects to remove from cache, or to remove objects by CP Code.

Easiest-to-use UI, quickest, removal-based or invalidation based. Optional email notification of results.

Must specify each object to be removed; For example, cannot specify a directory by wildcard.

Content Control Utility API (CCUAPI)

Same as the CCU UI, but a SOAP-based API.

You don’t have to log in to con-trol.akamai.com and can set up your own interface.

Same as CCU UI. Also, there is set up involved in using SOAP API and, if desired, creating an additional interface.

ECCUEnhanced Content Control Utility

A control.akamai.com Web UI that allows you to specify refresh-ing objects by rules involving path and extensions.

Easy to use rule-based UI. Pro-vides for inclusion of sets of objects by directory or exten-sion—not individual objects—to refresh by invalidation.

Cannot specify individual objects. Requests persist in a purge.data file, replaced only by requests with more recent timestamps using the same matches.

ECCU file upload Using the ECCU Web UI, you can upload ECCU files containing rule-based instruc-tions beyond path and extension.

More flexible and complex than Enhanced CCU GUI. Can fine tune refreshing based on request headers, request method, and other criteria.

Need to create the ECCU file, get the syntax right, etc. More flexibility and power means more potential for errors. Uses the same purge.data file as the ECCU GUI.

PublishECCU An EdgeControl Web Service SOAP-based API that allows you to upload ECCU files.

Provides essentially the same functionality as the ECCU file upload UI, since it provides for uploading ECCU files, but as a a SOAP-based API, you can develop and use a local interface instead of using a browser to log on Aka-mai EdgeControl.

You need to set up to use the SOAP API; otherwise the same as ECCU file upload.


Chapter 2. Content Control Utility

In This Chapter

The Content Control Utility (CCU) is a Web interface available on Akamai Edge-Control, control.akamai.com that allows you to specify the refreshing of specific cached objects, or to remove all objects specified by CP Codes.

The Content Control Utility (CCU) provides the option of using invalidation-based or removal-based refresh. See page 6 for a discussion of the differences between these two methods.

The Content Control Utility is available for most objects delivered through Akamai. For streaming services, removal of QuickTime, Real, and Windows Media objects is supported. Requests are propagated through the Akamai network, and most removals

are completed within 10 minutes of the request.

One limit is that files submitted for CCU requests should contain no more than about 100 URLs of about 400 characters in length. If you receive a “Request Entity Too Large” error, split your file into smaller files and try again."

You can submit any number of files containing about 100 URLs, but you should have no more than 10,000 outstanding requests at any one time. If you receive a Code 332 error, which indicates you have exceeded that limit, you should wait about 10 minutes and try again.

Also, the utility uses a software throttle to release requests to the network over time rather than send all at once, so that the more ARLs/URLs in a request, the longer it can take to complete.

The CCU request does not persist—it is executed by the edge server and then “for-gotten.” Any content matching the CCU request is removed one time. If another request comes for the content, a fresh copy will repopulate the cache.

Before YouBegin

Before you use the Content Control Utility:

You’ll need to have access to control.akamai.com. If you don’t have access to Edge-Control or to this Content Control Utility, check with your Akamai representative.

For a discussion of best practices—when to use this interface or a different content control interface, the advantages, disadvantages, and limitations of each, please see the Introduc-tion to this guide, and in particular the material beginning on page 7.

Using the Content Control Utility • 12

Submitting Requests • 12

About the Data Entry and the File Upload • 13

On-Screen Submission Confirmation • 15

Troubleshooting • 16


Content Control Utility

Using the Content Control Utility

SubmittingRequests

To submit refresh requests using the Content Control Utility:

1. Log in to control.akamai.com.

2. In the sidebar, click the product link for the product you want to work on.

3. Under the product, click the Content Control Utility link to display the Con-tent Control Utility page.

The Content Control Utility page contains both the CCU (Refresh by URL) and ECCU applications (Refresh by Directory and File Extension). The CCU option is the default; if it isn’t displayed, click the Refresh by URL link.

Figure 1. Refresh by URL (the CCU main page)

4. Choose the basic refresh method:

- Enter a list of ARLs/URLs you want to remove, OR

- Browse for a file containing the list of ARLs or URLs you want to remove OR

- Indicate the CP code for which you want to purge all associated content.

Note that ARLs/URLs must be full, not relative, and must include the protocol, which can be http://, https://, rtmp://, or mms://. For example:

http://www.example.com/graphics/picture.gif is OK

graphics/pictures.gif is NOT OK.



5. Indicate the Network on which to perform the refresh: Production or Staging. Staging refers to the Edge Staging Network (ESN).

6. Indicate the Refresh method: purge or invalidate.

Figure 2. The Content Control Utility page.

7. Optionally, enter email addresses for notifications of the results of your request.

8. Click the Start Refreshing Content button.

About the Data Entry and the File UploadThe following guidelines apply to the data entry for the ARLs and URLs and to the email addresses.

About the Data Entry for ARLs or URLs

When identifying objects to be removed from the Akamai network, note that you can specify either Akamai Resource Locators (ARLs) or Uniform Resource Locators (URLs). ARLs are discussed in “The Digital Property and the ARL” on page 37.

When entering requests to remove streaming media objects, you must enter the ARL/URL of the actual streaming object, such as rtsp://… or mms://…. CCU does not support entry of the metafile URL and will not remove the streaming media objects referenced in the metafile.



Specify URLs if you have an Akamaized domain and have CNAMED your site. These entries look like standard URLs because Akamai- and object-specific data reside in metadata for an Akamaized domain.

When you enter the ARLs/URLs to be removed in the ARLs/URLs field, you must enter only one per line. You can specify full ARLs that indicate the Akamai network and your CP code or use Akamaized host names in a URL. One limit is that files sub-mitted for CCU requests should contain no more than about 100 URLs of about 400 characters in length. If you receive a “Request Entity Too Large” error, split your file into smaller files and try again. You can submit any number of files containing about 100 URLs, but you should have no more than 10,000 outstanding requests at any one time. If you receive a Code 332 error, which indicates you have exceeded that limit, you should wait about 10 minutes and try again.

If You Upload a File Rather than list the objects, you can upload a text file containing the list of ARLs/URLs to be removed. ARLs/URLs identified in the text file must also be one to a line. Make sure that lines do not wrap and that there is a return character after each ARL. The same limits apply (see the previous paragraph).

If You Purge By CPCode

Rather than identifying the specific content to be removed, you can choose to remove all content associated with one or more CP codes; the CP codes associated with your Akamai EdgeControl login will be listed for your selection.

Caution: Removing or invalidating all objects under a CP code or top-level directory can cause high load on your origin server. All Akamai edge servers will fetch or revali-date these objects when next requested by an end user.

Removing Content or Invalidating Content

If you choose to remove content from the Akamai network, Akamai edge servers will re-retrieve the content from the origin server the next time they receive a request from one of the specified URLs.

If you choose to instead mark the content as invalidated, Akamai edge servers will revalidate the freshness of the content with an HTTP conditional GET (If-Modified-Since) request the next time they receive a request for one of the specified URLs. If the content has changed, the origin server will return a fresh copy of the content. If the content has not changed, the origin server will return an HTTP 304 Not Modi-fied response, using less network bandwidth than if content were returned.

About the Email Address(es) and Notification

You can optionally choose to enter e-mail addresses to which notifications of a com-pleted request should be sent. You can enter multiple e-mail addresses separated by commas, or you can choose not to be notified. Messages will be posted to the addresses, for example:

This message is to confirm your Akamai content removal request (101277051) has been processed by all active servers on our network.

Please contact us (877-4-AKATEC) if you have any questions or require further assistance.

Thank you from Akamai Customer Care.



On-Screen Submission Confirmation

Besides the email notifications, the Content Control Utility provides an on-screen message telling you whether your submission was accepted or rejected.

This message contains a Request ID you should keep track of. If you need to contact Akamai Customer Care with a question of problem about the purge request, having the request ID code on hand greatly facilitates the process.



Troubleshooting

This section discusses some common issues that can arise when using the Content Control Utility. Most deal with small errors in entering the content removal request and are easily remedied. Use this information to quickly diagnose and troubleshoot a problem.

If you are unable to diagnose or fix an issue, or need assistance with user names and passwords, please call your Akamai Account Manager, or contact Akamai Customer Care at 877-4-AKATEC (877-425-2832) or [email protected].

I am unable to access the Content Control Utility.

Akamai EdgeControl users must have tech or admin roles and must have the appro-priate items in their contracts to access Content Control Utility. If you have the appropriate role and line item and still cannot access the link, contact Customer Care. If you do not have the appropriate role or line item and feel you should, contact your Akamai Account Manager for further discussion.

I get the error 'You have exceeded your maximum number of outstanding purge ARLs'.

Your most recent request caused you to have over 10,000 total ARLs/URLs in the queue for purging. You cannot have more than 10,000 ARLs/URLs pending at once. Wait a few minutes to give some of your pending requests time to complete, then submit your request again.

I get the error message 'Badly formatted ARL'.

One of the following issues exists:

• The ARLs are not formatted correctly. Whether you manually submitted ARLs to the interface or uploaded a text file containing the ARLs to be removed, each ARL must be on its own line. Make sure there is a line break after each ARL. Use caution when copying and pasting ARLs from email or other files. Doing so sometimes causes the text to wrap, thereby breaking the ARLs. Fix the errors and try to resubmit the request.

• You've uploaded an incompatible file format. Content Control Utility accepts files in text format only. If you are uploading a file of ARLs to be removed, make sure the file is in text (.txt) format. Fix the errors and try to resubmit the request.

I get the error 'Illegal or unauthorized ARL'.


• You've uploaded an incompatible file format. Content Control Utility accepts files in text format only. If you are uploading a file of ARLs/URLs to be removed, make sure the file is in text (.txt) format. Fix the errors and try to resubmit the request.

• You are not authorized to remove these ARLs/URLs. You can only request removals of domains associated with your cpcode by your Account Manager. Contact your Account Manager for further assistance.


Troubleshooting

The CCU submission form is hanging instead of submitting the request, and I’m not receiving a request confirmation.

Try to make your content removal request again in approximately 15 minutes. If you still receive an error, contact Akamai Customer Care.

I haven't received notification that my content removal is complete.


• You did not enter any e-mail addresses when you made the removal request. If you wanted to be notified when a removal is complete, you must enter e-mail addresses at the time of the request. Content Control Utility does not use e-mail addresses associated with your login information for notifications.

• The notification e-mail addresses are invalid. You may have entered invalid e-mail addresses for notification of a completed content removal, but that doesn't necessarily mean that the content hasn't been removed. Contact Customer Care with your request ID numbers to check whether the process is complete.

• It’s possible that the content removal has occurred, but the Akamai user notifica-tion process is unable to confirm this removal. If you suspect this is occurring, check with Contact Customer Care with your request ID to check on the status of your request.

• The content removal has not yet occurred. When you submit a content removal request, the confirmation page will indicate an estimated time for completion. Check this time to see if the content removal should be complete. If you have further concerns, please contact Customer Care.

I’ve received email notification that my content removal is complete, but I’m still seeing old images.


• Your browser could be caching old images. Clear the cache in your browser and check the images again.

• Your Web servers could still contain old content. Make sure you replace old files with fresh content files on your Web server before you make a content removal request. Otherwise, after Akamai removes the content from Akamai servers, the old content will get re-distributed. If you didn't change the old content on your Web servers, replace it now and re-request the content removal.

• When removing streaming media content, make sure you have entered the ARL/URL for the actual streaming media object. Entering metafile URLs will not remove the content referenced in those metafiles.

I get an error that says Purging Service Not Available.

Try to make your content removal request again in approximately 15 minutes. If you still receive an error, contact Akamai Customer Care.

I get an error containing the words 'Internal Error'.

Please contact Akamai Customer Care at 1-877-4-AKATEC (877-425-2832) or at [email protected].


Chapter 3. Content Control Utility SOAP API

In This Chapter

The Akamai Content Control Utility SOAP API (CCUAPI) provides a mechanism, for Akamai customers to write programs that submit a list of cached objects to be removed from the Akamai network. CCUAPI uses Simple Object Access Protocol (SOAP) and HTTP or HTTPS as a transport layer.

The CCUAPI uses either the removal-based or the invalidation-based refresh method. See page 6 for a discussion of the differences between the methods, and see page 25 for information on the options in this API.

Programmers and administrators who use the Content Control Utility SOAP API to remove content from the Akamai network typically use CCUAPI one of two ways:

• To develop a GUI for developers or those who manage your Web content, rather than providing many users EdgeControl access.

• To integrate the API into a content management system. For example, you might want the act of publishing new content to the content management system to call a function that purges old content from the Akamai network.


This chapter provides:

• Guidelines for using CCUAPI and an overview of SOAP.

• A description of CCUAPI, including syntax.

• Instructions for using CCUAPI with Perl, Visual Basic, or Java with Axis.

Examples are provided in a separate zip archive, CCUAPI_examples.zip, available on control.akamai.com.

SupportedAkamai Services

The Content Control Utility is available for most objects cached and delivered through the Akamai network. For streaming services, removal of QuickTime, Real and Windows Media objects is supported.

Using CCUAPI • 20

Using CCUAPI with Perl • 20

Using CCUAPI with Visual Basic • 21

Using CCUAPI with Java and Axis • 22

CCUAPI Reference • 25

Syntax • 25

Function Output • 26

Result Codes and Troubleshooting • 27


Content Control Utility SOAP API

Using CCUAPI

Guidelines &Limits

Please note the following guidelines for using the CCUAPI:

• Akamai requires the use of HTTPS to maintain security.

• One limit is that files submitted for CCU requests should contain no more than about 100 URLs of about 400 characters in length. If you receive a “Request Entity Too Large” error, split your file into smaller files and try again.

• You can submit any number of files containing about 100 URLs, but you should have no more than 10,000 outstanding requests at any one time. If you receive a code 332 error, which indicates you have exceeded that limit, you should wait about 10 minutes and try again.

Setup You must have an EdgeControl user name and password with Content Control Util-ity permissions. Contact your Account Manager if you do not have this.

1. Download the appropriate WSDL, either from https://ccuapi.akamai.com, or log in at https://control.akamai.com and go to: HTTP Content Delivery -> Documentation -> Content Control Utility.

2. Download the CCUAPI Examples files and use the appropriates ones:

Note that some SOAP clients download the WSDL file on demand if you specify this URL when initializing the client.

Using CCUAPI with Perl

Perl-SpecificPrerequisites

Prior to using CCUAPI with Perl:

• Visit https://ccuapi.akamai.com/ccuapi.wsdl to download the WSDL file.

• Install Perl 5.005 or greater if Perl is not already installed on the system.

• Download the SOAP toolkit, SOAP::Lite, from http://www.soaplite.com/, and install it according to its instructions. Ensure that you download the required Perl packages as specified in the toolkit readme file and install SSL. Downloading SOAP::Lite without downloading the HTTPS library can result in an infinite loop.

• Remember to escape special characters from the API, for example, the “@” sign in the email notification.

If you use.... Download this File

Perl https://ccuapi.akamai.com/ccuapi.wsdl

MS Visual Basic 6, SOAP 1.0MS Visual Basic 6, SOAP 3.0MS Visual Basic .Net

https://ccuapi.akamai.com/ccuapi-list.wsdlhttps://ccuapi.akamai.com/ccuapi-list-2001.wsdlhttps://ccuapi.akamai.com/ccuapi-dotnet.wsdl

Java https://ccuapi.akamai.com/ccuapi-axis.wsdl


Using CCUAPI

UNIX Install SOAP::Lite requires XML::Parser to be installed. XML::Parser requires that you install Expat on your system prior to installing XML::Parser. SOAP::Lite SSL support requires that openssl be installed on your system.

A recommended approach to installing the SOAP::Lite and XML::Parser packages is to use CPAN. For example,

perl –MCPAN –e shell> install SOAP::Lite

• Download and install ActiveState Perl. A free and simple GUI install program is available from http://www.activestate.com/.

Using CCUAPI withPerl

To use CCUAPI with Perl:

1. Create a program that allows you to enter a username, password, email address for notification, as well as a file that contains a list of ARLs/URLs on the com-mand line. All arguments are required except for email, type, and action. You can check the usage by typing

perl <program name.>

See the code example, CCURequest.pl, in the separately supplied zip archive available on control.akamai.com.

2. Run the program, changing the arguments appropriately.

Please download the CCUAPI_examples.zip file for the full details of a Perl example.

Using CCUAPI with Visual Basic

VB-SpecificPrerequisites

• Install Microsoft’s SOAP client.

• Visit https://ccuapi.akamai.com/ccuapi-list.wsdl to download the appropriate WSDL file for Visual Basic.

VB Example Please download the CCUAPI_examples.zip file for the full details of this example. This example presents a form that allows the user to enter a username, password, and email address for notifications as well as a file that contains a list of ARLs/URLs. Clicking the Show URLs button displays the ARLs/URLs listed in the data file. Clicking the Purge URLs button removes objects based on the ARLs/URLs listed in the data file from the Akamai network.

Creating the Project To create the project, follow the instructions in VBExample.txt from the CCUAPI_examples.zip archive. You’ll create a new project, add the appropriate text boxes, buttons, and button methods, and create a new module with provided code.

Running the Program 1. From the Visual Basic menu, choose “Project | References...”, and check “Microsoft Soap Type Library”.

2. Run the program.

3. Enter your CCU username and password, and the full path/name of the file that contains the ARL/URL list in the appropriate text boxes.

4. Click Show URLs to verify that you have the correct list.


http://www.activestate.com/


5. Click Purge URLs to see the result code.

NOTE: If the result is not successful, please see Result Codes and Troubleshooting. For instance, if you do not have permission to purge the objects you attempted to remove, you will receive a “Format of URI is invalid” error message. Note that this CCUAPI interface module defines error code “410” to be a client error.

Specifying an EmailOption

You must escape special characters using ASCII codes using the format Chr(<ASCII code>). Specifying an email option within VB code for CCUAPI could look like:

Options(0) = “email” & Chr(45) & “notification” & Chr(58) & “ccuadmin” & Chr(64) & “examplecontrol.akamai.com” & Chr(46) & “com”

See an ASCII code reference like http://www.ascii.cl for a list of codes.

Using CCUAPI with Java and Axis

This information is meant to provide only an introduction to the usage of the CCUAPI with Java and Axis 1.3, 1.2 or 1.1. Our customers typically develop their own applications that use the API. Akamai recommends that you do the same based on the API specifications.

The following is a detailed procedure on how to install and configure Axis, Xerces, and the CCURequest commandline client example (tested under Windows, UNIX, and Cygwin). Please note that the CCUAPI requires all purge requests to be sent over SSL.

Java-Specific Prerequisites• The relevant files in CCUAPI_examples.zip ccuapi-axis.wsdl, URLReader.java,

and CCURequest.java. In this example, place these files in ccuapi-axis.

• You must have an EdgeControl user name and password with Content Control Utility permissions. Contact your Account Manager if you do not have this access.

• To enable the use of SSL, install the CA root certificate (gte_global_root.der Windows and gte_global_root.pem for Unix). This is the SSL certificate Akamai uses for CCUAPI, and these are also found in CCUAPI_examples.zip

• Use JDK 1.4 We recommend installing the Java SDK 1.4 from "http://java.sun.com/j2ee/1.4/download.html.

• Use a Java SOAP toolkit. This example uses Axis version 1.3, and the setup also works with Axis 1.2 and 1.1.

Installing Axis & Xerces

If you already have Axis and Xerces installed, skip this set of steps and move on to the next set of steps.

If you don’t have Axis and Xerces installed, follow these steps:

1. Create a folder or directory into which you will unpack the Axis and Xerces files. If you're just trying out CCUAPI, make a directory called “ccuapi-axis,” the name we’ve chosen for this example.


http://java.sun.com/j2ee/1.4/download.html

Using CCUAPI

1. Download axis-bin-1_3.zip from the Apache site: http://ws.apache.org/axis/

2. Download Xerces-J-bin.2.7.1.zip from the Apache site: http://xerces.apache.org/xerces2-j/

3. Unzip the Axis and Xerces .ZIP files into the ccuapi-axis directory.

Setting up the Environment

1. Set the Java CLASSPATH environment variable (in these instructions, PATH_TO_XXX_DIRECTORY must be replaced with the directory holding the Axis and Xerces packages).

Note that the CLASSPATH update appends the AXISCLASSPATH to your CLASSPATH; if you make a mistake, it may be necessary to remove the added elements and retry. Closing the shell and starting a new one should be sufficient.

In UNIX: export AXIS_HOME="PATH_TO_AXIS_DIRECTORY/axis-1_3"export XERCES_HOME="PATH_TO_XERCES_DIRECTORY/xerces-2_7_1"export AXIS_LIB="$AXIS_HOME/lib"export AXISCLASSPATH="$AXIS_LIB/axis.jar:$AXIS_LIB/commons-discovery-

0.2.jar:$AXIS_LIB/commons-logging-1.0.4.jar:$AXIS_LIB/jaxrpc.jar:$AXIS_LIB/saaj.jar:$AXIS_LIB/log4j-1.2.8.jar:$XERCES_HOME/xml-apis.jar:$AXIS_LIB/wsdl4j-1.5.1.jar:$XERCES_HOME/xercesImpl.jar"

export CLASSPATH="$CLASSPATH:$AXISCLASSPATH"

In Windows: set AXIS_HOME=PATH_TO_AXIS_DIRECTORY\axis-1_3set XERCES_HOME=PATH_TO_XERCES_DIRECTORY\xerces-2_7_1set AXIS_LIB=%AXIS_HOME%\libset AXISCLASSPATH=%AXIS_LIB%\axis.jar;%AXIS_LIB%\commons-discovery-

0.2.jar;%AXIS_LIB%\commons-logging-1.0.4.jar;%AXIS_LIB%\jaxrpc.jar;%AXIS_LIB%\saaj.jar;%AXIS_LIB%\log4j-1.2.8.jar;%XERCES_HOME%\xml-apis.jar;%AXIS_LIB%\wsdl4j-1.5.1.jar;%XERCES_HOME%\xercesImpl.jar

set CLASSPATH=%CLASSPATH%;%AXISCLASSPATH%

In Cygwin: export AXIS_HOME="PATH_TO_AXIS_DIRECTORY/axis-1_3"export XERCES_HOME="PATH_TO_XERCES_DIRECTORY/xerces-2_7_1"export AXIS_LIB="$AXIS_HOME/lib"export AXISCLASSPATH="$AXIS_LIB/axis.jar;$AXIS_LIB/commons-discovery-

0.2.jar;$AXIS_LIB/commons-logging-1.0.4.jar;$AXIS_LIB/jaxrpc.jar;$AXIS_LIB/saaj.jar;$AXIS_LIB/log4j-1.2.8.jar;$XERCES_HOME/xml-apis.jar;$AXIS_LIB/wsdl4j-1.5.1.jar;$XERCES_HOME/xercesImpl.jar"

export CLASSPATH="$CLASSPATH;$AXISCLASSPATH"

2. Make sure that “java” and “javac” are in your PATH; add the appropriate JDK or JRE directory, if needed.

3. If you haven’t already done this: from the CCUAPI_examples.zip, unzip the Java files—CCURequest.java, URLReader.java, and the WSDL, ccuapi-java.wsdl—into your Axis/Xerces working directory, ccuapi-axis.

4. Generate stubs from “ccuapi-axis.wsdl”:

java org.apache.axis.wsdl.WSDL2Java ccuapi-axis/ccuapi-axis.wsdl

5. Copy the command line client example (CCURequest.java and URLReader.java from CCUAPI_examples.zip) into “com/akamai/www/purge/”:


http://ws.apache.org/axis/

http://xerces.apache.org/xerces2-j/


cp ccuapi-axis/CCURequest.java com/akamai/www/purge/CCURequest.javacp ccuapi-axis/URLReader.java com/akamai/www/purge/URLReader.java

Or in Windows:

COPY \ccuapi-axis\CCURequest.java \com\akamai\www\purge\CCURequest.java

COPY \ccuapi-axis\URLReader.java \com\akamai\www\purge\URLReader.java

6. Compile the commandline client:

javac com/akamai/www/purge/CCURequest.java com/akamai/www/purge/URLReader.java com/akamai/www/purge/JavaClasses.java com/akamai/www/purge/JavaClassesLocator.java com/akamai/www/purge/PurgeApi.java com/akamai/www/purge/PurgeApiSOAPBindingStub.java com/akamai/www/purge/PurgeResult.java

Testing CCUAPI

Put a test URL into a file called “ccuapi.in” and test CCUAPI.

In UNIX: java -cp "$AXISCLASSPATH:." com.akamai.www.purge.CCURequest -user your_username -pwd your_password -file ccuapi.in

In Windows: java -cp %AXISCLASSPATH%;. com.akamai.www.purge.CCURequest -user your_username -pwd your_password -file ccuapi.in

In Cygwin: java -cp "$AXISCLASSPATH;." com.akamai.www.purge.CCURequest -user your_username -pwd your_password -file ccuapi.in

CP Code Example The above examples are to purge a specific URL. This Windows example is for a refresh using a CP Code. Only administrative level users can purge by CP Code; this type of purge can be inefficient and use extensive resources.

java -cp %AXISCLASSPATH%;. com.akamai.www.purge.CCURequest -user your_username -pwd your_password -type cpcode -file ccuapi.in

SSL Problem?Is Cert Installed?

You should see a success message. If you have SSL negotiation problems, you may need install the GTE root CA certificate into your Java runtime's cacerts file. This should not be necessary with JDK 1.4, which ships with this certificate CA prein-stalled. The command will look like this for UNIX

keytool -import -trustcacerts -keystore $JAVA_HOME/jre/lib/security/cacerts -file CCUAPI_examples/gte_global_root.pem

Or in Windows:

keytool -import -trustcacerts -keystore %JAVA_HOME%\jre\lib\security\cacerts -file CCUAPI-axis\gte_global_root.der

The default passphrase from the Java distribution is “changeit.” After adding the CA certificate, retry the test.


CCUAPI Reference

CCUAPI Reference

The following sections describe the syntax and elements of CCUAPI.

Syntax This syntax example that assigns the output of the function called purgeRequest to the variable result:

PurgeResult result =purgeRequest(user, pwd, network, options[],uri[])

Function Detail The function PurgeRequest takes the following parameters:

Parameter Description

user Username for https://control.akamai.com; case sensitive.

pwd Password for https://control.akamai.com; case sensitive.

network Deprecated; this parameter is ignored by CCUAPI. Use the empty string ("") as a value for this parameter.

options Array of options: action, domain, email-notification, or type.Case insensitive. If you use multiple options (for example, action and email-notification, put each option in a separate element of the array.You should include any option you want to set.

action Specify whether the object should be removed from cache, resulting in a full GET request to origin, or invalidated, resulting in an IMS GET request. The syntax is:action=removeaction=invalidate

domain Specify the network: remove from staging (Edge Staging Net-work, or ESN) or production (the default). The syntax is:domain=productiondomain=staging

email-notification

Specify email addresses for completed removal notifications: email-notification [email protected]

To send notification to multiple email addresses, the 'options' argument must be formatted to contain a comma-separated list of email addresses:

[email protected],[email protected]: Remember to escape the “@” sign and all other special charac-ters if necessary.

type Specify whether the strings in the uri array are ARLs/URLs representing individual objects, or if they are CP codes that should be interpreted as requests to purge all content associated with that CP code. The syntax is:

type=arltype=cpcode

NOTE: To use the type cpcode option, your administrator must enable purge-by-cpcode access for your username through Akamai EdgeCon-trol.



Function Output The elements in the PurgeRequest structure include the following:r

Sample Output Output from the content removal request can look like the following:

resultCode: 100; resultMsg: Success; sessionID: 29361; estTime: 540; uriIndex: -1;

When this function returns, it indicates that your purge request is put in the queue, to be processed by the Akamai network. A notification at the email you specified indicates that the content has been removed from the network.

The resultCode elements are defined in the next section.

uri An array of ARLs/URLs to be purged from the network, or an array of CP codes, depending on what was specified in the parameter options. Case sensitive.

NOTE: All members of this array must of the same type, either all ARLs/URLs, or all CP codes. Wildcards are not supported. You must fully spec-ify the ARLs/URLs to be purged.

Note: If you are using Perl with SOAP::Lite and using the option type cpcode, you may have to include a space before the CP code value so that SOAP::Lite sends it as a string. For example:purgeRequest("username", "password", "", [ "type=cpcode", "action=invalidate" ] , [ " 555" ]);

ARL/URL Examples:Standard Akamai edge server configuration: http://www.example.com/logo.gif

FreeFlow: http://a9.g.akamai.net/7/2/3/4/www.example.com/logo.gif

Parameter Description

Element Type Description

resultCode Int Indicates success or failure of removal request.

resultMsg String Explains result code

sessionID String Unique ID assigned to the removal request.

estTime Int Indicates the estimated time for the request to be pro-cessed, in seconds. A value of -1 indicates that there is no estimated time, usually appearing when the request fails.

uriIndex Int If the request fails because of a bad ARL/URL, this identi-fies the index of the first failed ARL/URL in the array. A value of -1 indicates there were no bad ARLs/URLs, or that an error occurred before the ARLs/URLs were parsed.


CCUAPI Reference

Result Codes and Troubleshooting

This section provides an overview of CCUAPI result codes, as well as their definitions and the steps you can take to correct the issues.

If you need further assistance, call your Akamai Integration Consultant, or contact Customer Care at 877-4-AKATEC (877-425-2832) or [email protected].

Result codes are patterned as follows:

1xx Text Message

The follow table outlines specific result codes that you may encounter while making a purge request and provides troubleshooting information for codes that correspond to failed requests. Additional result codes might be added as necessary.

Code Element Indicates

1xx Successful Request

2xx Warning; reserved. The removal request has been accepted.

3xx Bad or invalid request.

4xx Contact Akamai Customer Care.

Code indicates Troubleshoot

301 Invalid username or password

Your Akamai portal username & password must have a tech or admin role and the appropriate contract associ-ation. Contact your Akamai Account Manager if you believe your login information is inaccurate.

302 Bad syntax for an option.

303 Invalid value for an option.

To send notification to multiple email addresses, the 'options' argument must be formatted to contain a comma-separated list of email addresses:[email protected],[email protected]

Formatting as follows does not work: [email protected] [email protected]: Users must remember to escape the “@” sign and all other special characters if necessary.

304 Option already pro-vided.

Multiple email notification addresses are formatted incorrectly.

320 URI provided Make sure that the ARLs/URLs to be removed are spec-ified in the request.

321 Format of ARL/URL is invalid

Make sure each string has only one ARL/URL. ARLs/URLs using streaming protocols are not currently sup-ported.



The “Request Entity Too Large” (413) Error

This error comes from a source other than the CCUAPI-code based errors above. If you receive this error, you have exceeded the file-limit for the submission. There is a limit to the file size submission of about 100 URLs of about 400 characters in length. If you receive this error, split your request up into multiple smaller requests and try again.

322 You are not autho-rized to purge this ARL/URL

CCU compares you URI requests to your CP code and domain. You can only request removals of domains associated with your CP code. Contact your Account Manager for further assistance.

323 ARL/URL illegal CCU compares you URI requests to your CP code and domain. You can only request removals of domains associated with your CP code. Contact your Account Manager for further assistance.

332 Maximum number of ARL/URLs in out-standing purge requests exceeded

No more than 10,000 ARLs/URLs can be pending at any given time. If you receive errors, wait about 10 minutes and try again.

401, 402 Error Contact Akamai Customer Care at 877-AKATEC (877-425-2832) or [email protected].

Code indicates Troubleshoot


Chapter 4. Enhanced Content Control Utility

In This Chapter

The Enhanced Content Control Utility (ECCU) is a GUI available on Akamai Edge-Control, https://control.akamai.com that allows you to specify the refreshing of cached objects through two ways:

• You can use rules involving path and extensions that could be summarized as, “Refresh objects with this extension in this path.”

• You can upload ECCU files, enabling you to specify more complex rules by which objects will be refreshed—not only path or extension, but also using crite-ria such as the contents of requests, cookies, CP codes, or other criteria.

The Enhanced CCU uses an invalidation-based refresh method. That is, once it receives the refresh instructions, the cached instance is marked as invalid. The Aka-mai server receiving a client request for objects matching the particular path and extensions sends an If-Modified-Since—a conditional GET—to the origin. If it finds a newer version at the origin, it removes the existing cached instance and replaces it with the newer version fetched from the origin.

Before YouBegin

• The ECCU applies to content configured for control with edge server configura-tion files. If your content does not use a configuration file, use the CCU.

• You’ll need to have access to https://control.akamai.com. If you don’t have access to this Content Control Utility, check with your Akamai representative.

• Familiarize yourself with how this tool works, as discussed in subsequent sec-tions. The specific kind of path and extension formulations may be new to many.


Before You Upload ECCU Files

You’ll need to be familiar with Digital Properties (page 37) and with the ECCU file structure and options (page 39).

Before You Begin • 29

Using the ECCU • 30

Viewing Previous Refresh Requests • 32

About the Data Fields • 33

ECCU Status Messages • 34


Enhanced Content Control Utility

Using the ECCU

To use the ECCU:

1. Log in to control.akamai.com.

2. In the sidebar, click the product link for the product you want to work on.

3. Under the product, click the Content Control Utility link.

The Content Control Utility Content page contains both the CCU (Refresh by URL) and ECCU applications (Refresh by Directory and File Extension). The CCU page (shown in Figure 1 on page 12) is the default.

4. Click the Refresh by Directory & File Extension link to view the ECCU page.

Figure 3. The Content Control Utility Link on the Manage tab page.

See page 33 for definitions of the data you see on this page. For information on the Digital Property and ECCU file structure, see pages 37 and 39, respectively.

5. Select the Digital Property Name(s) and, optionally, give this request a name to identify it in the future.


Using the ECCU

6. Choose the refresh method:

- Refresh all files in a directory

- Refresh by directory and extension

- Upload an ECCU file containing the refresh instructions.

Figure 4. Selecting the files to refresh

7. When you’re ready, click the Next button to go to a confirmation page on which you can review your submission before finalizing it.

8. On the confirmation page, review your data and when ready, click the Submit Request button.

The Metadata you see on the confirmation page is the ECCU file, the encoded refresh rules, which is described on page 39.

9. The successful submission takes you to the Request Submitted page, where you should note the displayed Request ID that can be used for tracking and problem solving. If you want, click Refresh Content to return to the ECCU main page.



Viewing Previous Refresh Requests

To view previous requests and their associated metadata:

On the Refresh Content page (see Figure 4 on page 31) click the View Previous Refresh Requests link to view a table of previous requests.

Figure 5. Viewing Previous Refresh Requests

In this table, you can click View Details to view more data, including the metadata code for the file, which is described on 39. The Status messages are described on page 34. You can also use the display options at the bottom to sort the table or change the number of files displayed.

Resubmitting aRequest

To resubmit a request displayed in the list of previously submitted requests, click the Resubmit link for the request, then on the next page, confirm by clicking the Submit Request button.


About the Data Fields

About the Data Fields

When you enter the refresh instructions (Figure 4), you use the following data:

• Name (optional)

The Name is for your convenience should you later want to refresh content using the same criteria. It’s a note to yourself or your co-workers. For example, “logo images cleanup” or “test directories cleanup.”

• Digital Property Name, Type, and Match (presence or absence of “*”)

Select the Digital Property Name(s) you want to work on. You can select up to 20 names.

The Property Type (ARL Token or Host Header) is at the right of the name.

If the property is an inexact match, it is preceded by a wildcard asterisk, as in “*.example.com”. Exact matches show no wildcard, as in “www.example.com”.

The digital property name, type, and match, are described in “About Digital Properties” on page 37.

• Directory

- To specify the root directory, use “/” by itself, and in any case, the path should start with a “/”. Note that if the match is inexact, the match is for any root directory matching the property name. For example, if the property is *.example.com, and you use / for the directory, you’re giving instructions to refresh everything under test.example.com/, www2.example.com, another.example.com/, and so forth. However, this would not match new-example.com.

- When you specify a directory, its subdirectories are automatically included.

- Don’t use wildcard characters (? *), dots (.), commas (,) or semi-colons (;).

• Files to Refresh

You can choose to refresh all files in the directory, or you can specify the file extensions to refresh. If you choose to refresh by extension:

- Don’t use dots, wildcard characters, commas or semi-colons (. * ? , ;) in the extensions. That is, “gif ” is OK, but the following are NOT OK: “.gif ”, “htm*” or “htm?”.

- Case doesn’t matter: “GIF” is the same as “gif ”.

- To enter a number of extensions, separate each by a space, for example, “gif jpeg jpg html htm tiff tif.”

• Use the Following ECCU Files

See information on the Digital Property and ECCU file structure, on pages 37 and 39, respectively.

• Email (optional)

If you want email notification when the request is processed, enter the email address you want notified.



ECCU Status Messages

In the list of most recent refresh requests, the right-most column shows whether the request is pending, has completed successfully, or has failed. If you click the View Details link, you’ll see more complete status messages.

InformationalMessages

The possible informational messages you’ll see are:

• File uploaded and awaiting processing

• File successfully transferred to the validation server, and waiting for validation

• File successfully validated and waiting for deployment to Akamai's network

• File successfully deployed to Akamai's network

• File obsoleted by the validation server since a newer version is available

With the exception of the last message, the “obsolete” message, these messages simply indicate the stages in the successful implementation of your instructions.

For the “File obsoleted” message, no action is necessary. This message indicates you have submitted new instructions that make the old ones invalid.

Error Messages The possible error messages you’ll see are:

• File transfer to the validation server has failed

• File Invalid (Internal Error)

• Error during deployment to Akamai's network

These messages indicate that your refresh instructions have not been deployed, and they are accompanied by extended messages describing the specific error.

If you want the refresh to occur, you’ll need to fix whatever caused the error. Contact Customer Care if you need help.


Chapter 5. ECCU Publisher (PublishECCU)

The ECCU Publisher (PublishECCU) is an EdgeControl Web Service, a SOAP API.

EdgeControl Web Services allow you to access many EdgeControl services using a SOAP-based interface instead of a browser.

Web services use the same access and permissions, and the same user names and pass-words, that you would use to access Akamai EdgeControl by browser. Your SOAP cli-ent uses HTTP Basic Authentication to transmit the user name and password in the SOAP request.

Akamai provides the Web Services Description Language (WSDL) files to use in your SOAP-based interface and sample code to create HTTP Basic Authentication access to the services.

ECCU Publisher The PublishECCU API provides methods to upload ECCU files to the Akamai net-work, view and modify attributes of previously uploaded files, or delete these files.

ECCU (Enhanced Content Control Utility) file structure is used to specify files to refresh on the Akamai network using path criteria such as the directories or exten-sions, or using certain HTTP request or response properties.

When you use ECCU files, you work with the ECCU structure and syntax, and you work with the Digital Property. The ECCU file and digital properties are described in other chapters in this document.

For a discussion of best practices—when to use this interface or a different content control interface, the advantages, disadvantages, and limitations of each, please see the Introduc-tion to this guide, and in particular the material beginning on page 7. ECCU File best practices are described on page page 42.


ECCU Publisher (PublishECCU)


Chapter 6. About Digital Properties

Many Web Services as well as browser-based upload functions on Akamai EdgeCon-trol require the use of digital properties. For example, you use digital properties when you when you work with ECCU files or with WAR files in the EdgeComputing envi-ronment. The digital property identifies the hosts you’re working with, its name and type.

The PropertyName, Type, and Exact / Inexact Match

In the Web interfaces, you’ll see data entry for Digital Property Name and Type. Normally, these are described together—for example, example.com (ARL Token) or example.com (Host Header), are names followed by types in parentheses.

In the Web Services SOAP APIs, you’ll see fields such as propertyName or proper-tyNameExactMatch

Digital Property Attributes Configured in Setup, Not in These Interfaces

The following material describes these data in more detail. It is important to note that these values are set when Akamai configuration for your site is set up; the names are not necessarily the same as your origin name, and they cannot be set or changed in these interfaces. You can view your property names and associated attributes in the Enhanced Content Control Utility or ECCU file upload interface on the control.aka-mai.com management center, as described elsewhere in this document. If you have questions, check with your Akamai representative.

The Digital Propertyand the ARL

A digital property, defined by its name, type, and whether it is an exact match, iden-tifies the set of objects you’re working on, and to understand what it is, you need first to understand the ARL.

The ARL (Akamai Resource Location) is similar to the URL, the difference being that the ARL is specifically defined for objects to be served via the Akamai network. There are two types of ARLs:

• The v1 ARL

This is the original ARL used in the Akamai Freeflow Network, and it contains data coded into its structure. Such an ARL might look like this:

http://a123.g.akamai.net/7/123/456/e358f5de00e9/www.example.com/logo.gif

The “example.com”—the portion that looks like a host name, is the ARL Token, a digital property type that is further discussed in the next subsection. It is a token because it refers to a hostname but is not necessarily in the form of a host name.


About Digital Properties

• The v2 ARL

On Akamai edge servers, configuration files provide extensive content control. The properties previously specified in the v1 ARL, along with many other prop-erties, are defined in these files. The v2 ARL resembles a common URL:

http://www.example.com/logo.gif

The “example.com” is called a Host Header, the other digital property type. Sim-ply, it is in the hostname that appears in the “Host:” header sent by the client browser; thus, Host Header.

The Property Name and Types—Host Header or ARL Token

The “example.com” in the above ARLs is the property name, and it is either of the type Host Header or ARL Token, depending on the ARL type, v1 or v2, with which it is associated.

The type then tells the Akamai network whether content control information is con-tained in the ARL, or whether all such information is contained in a configuration file. When you work with ECCU files, you’ll need to know the type.

Exact Match or RHS? Other than name and type, the attribute associated with the property is whether it is an exact or inexact (RHS, or Right Hand Side) match.

• With an exact match, “example.com” would not match “test.example.com” or other subdomains of example.com.

• With an inexact, or RHS match, “example.com” matches “test.example.com” and other subdomains. The RHS match does not include “example.com.au” or “example.co.uk,” nor would it include “anotherexample.com.”

The Digital Property May Represent Many Hostnames

The preceding paragraphs on exact vs. inexact match touched on this, but to be explicit: you digital properties can represent many hostnames.

For example, if your digital property is “example.com” it can represent several subdo-mains—www.example.com, www2.example.com, good.example.com, bad.exam-ple.com, unclear.example.com.

To Limit an ECCU Refresh Request to Certain Hostnames

A request to refresh content on the digital property “example.com” will cause the con-tent to be refreshed for all of these hostnames. To limit the invalidation to a particular hostname, you should use the criteria of matching the request header match on the Host: header, and this can be done only on a Host Header property type.


Chapter 7. Enhanced CCU Request Format

In This Chapter

This chapter describes the format of the Enhanced CCU request file and the meta-data tags that can be used to define a refresh, or revalidate, request.

You can submit an Enhanced CCU request file to Akamai through ECCU file upload using the Enhanced Content Control Utility (ECCU) Web interface on the manage-ment center, or through the ECCU Publisher web service. The ECCU structure is also used directly with the ECCU Web interface, but requests made using the GUI are limited to path and extension matches. You can also view the resulting ECCU data in that interface.


Format of an Enhanced CCU Request

An Enhanced CCU file is a straight text file in a simplified XML format. The tags available in the file are:

• <eccu> </eccu> as opening and closing tags to indicate the type of the file.

• <match> tags to define the URI for the object or some other attributes by which to identify the objects to be revalidated.

• <revalidate> to specify a timestamp value. Objects with older timestamps must be revalidated before they are served.

In simplified form the file would look like this.

<eccu><match:tagname value=”value”>

<revalidate>epochtime | now </revalidate></match:tagname>

</eccu>

Format of an Enhanced CCU Request • 39

Rules for Proper Syntax • 40

Revalidation Examples • 40

The Revalidate Tag • 43

Match Tags • 44

Summary of Matches Used to Revalidate Content • 45

Path Matches • 46

Request Property Matches • 49

Response Property Matches • 57


Enhanced CCU Request Format

The following is a practical example of an Enhanced CCU file that purges the object referenced by the following URL/path:

http://www.example.com/products/images/*.gif, *.jpg

<eccu><match:recursive-dirs value=”products”>

<match:recursive-dirs value=”images”><match:ext value=”gif jpg”>

<revalidate>1046581729</revalidate></match:filename>

</match:recursive-dirs></match:recursive-dirs>

</eccu>

Note that this general invalidation (that is, all files under the images subdirectory with gif and jpg extensions, as opposed to specifying specific files) is the kind of refresh that the Enhanced CCU is designed to provide.

Rules for Proper Syntax

The following rules are essential to producing syntactically correct refresh/revalida-tion requests:

• The file must start and close with the <eccu></eccu> tags.

• Tag names and content strings are case-sensitive. Tag names must use lower-case throughout, and the match tag value is matched in a case-sensitive manner.

• Files can contain multiple revalidate tags. However, you cannot have two identi-cal matches at any level in the tree. See the example on page 43.

Revalidation Examples

This section shows some example Enhanced CCU requests—it is not complete or exhaustive but is meant to be representative. It is followed by examples of Best Prac-tices in requests (page 42).

Based on the DigitalProperty

You can invalidate all content associated with a Digital Property by submitting a request file that contains only the revalidate tag.

<eccu><revalidate>1046581729</revalidate>

</eccu>

The Digital Property to which this request applies is described in the chapter, “About Digital Properties” on page 37. Note that a Digital Property may encompass many hostnames.

Caution: A request over an entire digital property may cause a great deal of content revalidation and thus may cause a greatly increased request load on origin server. You should use this type of request only if you intend to revalidate all content served under a particular Digital Property.


Format of an Enhanced CCU Request

Based on HostHeader

A Digital Property may encompass many possible hostnames (for example, the Digi-tal Property *.example.com would include images.example.com, www.example.com, any.example.com). Often it is more practical to restrict the revalidation to a particular hostname by enclosing the revalidate tag in a match on the Host header in the request. This request causes all requests from www.example.com to be revalidated.

<eccu><match:request-header operation="name-value-cmp" argument1="Host"

argument2="www.example.com"><revalidate>now</revalidate>

</match:request-header></eccu>

Since the request-header match allows for substring comparisons on the value of the header, you could expand this request to revalidate all content served from any sub-domain of example.com.

<eccu><match:request-header operation="name-value-strstr" argument1="Host"

argument2=".example.com"><revalidate>1046581729</revalidate>

</match:request-header></eccu>

Based on DirectoryStructure

You might wish to invalidate only the content served from a particular directory under a particular hostname. For example, you might want to invalidate all content served from the “dailyspecials” directory of www.example.com.

<eccu><match:recursive-dirs value="dailyspecials">

<match:request-header operation="name-value-cmp" argument1="Host" argument2="www.example.com">

<revalidate>1046581729</revalidate></match:request-header>

</match:recursive-dirs></eccu>

The instructions above cause all of the files in the “dailyspecials” directory and its subdirectories to be revalidated.

Path Matches Cannot be Nested

Path matches cannot be enclosed in other match types. You’ll notice in the example above that the request-header match is enclosed inside the directory match, even though you might consider the hostname of a request to be more general than the directory (or, in this sense, the URL path component). However, you can use multi-ple matches in a single request (see page 42).

Based On FileExtension

If the entire web site has been republished, you might want to force revalidation of a large number of files. For example, you might want to revalidate all files with the extension .html. This could be accomplished with a single match on the extension:

<eccu><match:ext value=”html”>

<revalidate>now</revalidate></match:ext>

</eccu>



Best Practices in Requests: Use Space-Separated Values

The number of ECCU revalidate requests that can be included in the configuration for a single host header is limited to keep the invalidations from piling up endlessly. Submitting more than 250 invalidation requests at one time can result in a “global invalidation” –revalidating all content for that host header.

The way to avoid this is to invalidate multiple objects or paths in one request. You do this by using multiple, space-separated values for matches. Since each value is evalu-ated separately in only one request, this is a more effective way to submit requests.

Here’s an example match using multiple values separated by spaces.

The Right Way<match:recursive-dirs value="dir_1 dir_2 dir_3">

<revalidate>now</revalidate></match:recursive-dirs>

This is more efficient and a much better practice than creating three matches that look like this:

The Wrong Way<match:recursive-dirs value="dir_1">

<revalidate>now</revalidate></match:recursive-dirs>

<match:recursive-dirs value="dir_2"><revalidate>now</revalidate></match:recursive-dirs>

<match:recursive-dirs value="dir_3"><revalidate>now</revalidate>

</match:recursive-dirs>

Multiple Levels,Multiple Matches

Multiple matches can be applied to multiple levels. For example, to invalidate a “end-point name” in multiple trees, enclose the intermediate names in a single match. This is valid:

<match:recursive-dirs value="top_dir"><match:recursive-dirs value="mid_dir_1 mid_dir_2 mid_dir_3">

<match:recursive-dirs value="end_dir"><revalidate>now</revalidate>


</match:recursive-dirs

This one request would replace 12 individually built requests:

<match:recursive-dirs value="top_dir"><match:recursive-dirs value="mid_dir_1 mid_dir_2 mid_dir_3">

<match:recursive-dirs value="end_dir_1 end_dir_2 end_dir_3 end_dir_4"><revalidate>now</revalidate>


</match:recursive-dirs


The Revalidate Tag

The Revalidate Tag

The <revalidate> tag indicates a timestamp after which any content in cache with an older timestamp will be considered stale. The timestamp in the tag is normally the current time, to effect a revalidation on the next request from “now” and thus ensure that every edge server will revalidate its copy of the file.

The timestamp may be a time in the past, though it should never be a time before the content was last changed on the origin server. Otherwise, old versions of the content may persist in cache. The tag has the following syntax:

<revalidate>1113551040</revalidate><revalidate>now</revalidate>

The content of the tag may be:

• The key word, now, telling the system to process the request as soon as possible, with now meaning the time that Akamai receives the request.

• An integer representing an epoch time. In the above example, the 1113551040 statement means, “revalidate the file with an If-Modified-Since request to the origin if it was last validated before “Fri Apr 15 07:44:00 2005 UTC.”

Using MultipleRevalidate Tags

Files can contain multiple revalidate tags. However, you cannot have two identical matches at any level in the tree.

For example, the following is invalid because the match on foo valley” appears twice at the same level:

<match:foo value="a"> <match:bar value="b">

<revalidate>now</revalidate></match:bar>

</match:foo><match:foo value="a">

<match:bar value="c"><revalidate>now</revalidate>

</match:bar></match:foo>

The valid form of the above statement removes the duplication:

<match:foo value="a"><match:bar value="b">

<revalidate>now</revalidate></match:bar><match:bar value="c">

<revalidate>now</revalidate></match:bar>

</match:foo>

About Epoch Time The time for the <revalidate> tag is in Unix “epoch time” format. This time is the number of seconds that have passed since 1 January 1970 00:00 UTC. You can find the current epoch time with the following Unix command:

$ date +%s



1010705782

You can print the Unix epoch time of a particular time string as follows. (Note the example uses a very special date in the Pacific time zone corresponding to the epoch time with “nine nines”.)

$ date -d 'Sat Sep 8 18:46:39 PDT 2001' +%s999999999

That same epoch time in a different time zone:

$ date -d 'Sun Sep 9 01:46:39 UTC 2001' +%s999999999

So you can specify the time in any time zone and it will be the same on every Unix machine (provided their date setting is correct). Unix has done the conversion from your time zone to UTC for you.

However, for clarity it's always best to express times in GMT or UTC, since this is the time zone used by Akamai servers and it avoids errors due to time zone conver-sion and daylight-saving-time changes.

Match Tags

There are three types of matching you can perform in an Enhanced CCU request:

Path matching is used to describe the URL path

Request property matching is used to identify the request by some attribute other than its URL. Commonly used properties of requests include: query string arguments, file extensions, method (POST or GET)

Response property matching is used to identify the request by some attribute in the response from the origin server. In this case, there is only one match type available: response-header.

The table on the next page summarizes the available matches, and it is followed by an extensive discussion of the matches and how they are used.


Match Tags

Summary of Matches Used to Revalidate ContentType Tag Usage

URL Path recursive-dirs Match on the URL path components by name. Lets you invalidate all URLs that begin with a particular directory structure. Can nest only inside path matches.

sub-dirs-only Match on all subdirectories of a given directory. Treats the directory name like ‘*’, as in: /named-dir/*/named-dir/filename.extCan nest only inside path matches.

this-dir Constrains the invalidation to the current directory. Otherwise it would apply to all sub-directories of the given directory.Can nest only inside path matches.

filename See Caution belowa. Matches on the exact filename, nests only inside path matches.

a. Use these matches with caution! You can create a large number of unique matches and thus build a large purge.data file and adversely affect site performance. See the discussion, “ECCU Limitations” on page 8.

Request Property

ext Matches on the given file extensions. You can list multiple extensions and it is recursive, so that a single match will apply to all files with the given extension in all directories unless you nest this inside a URL path match.

cookie See Caution belowa. Matches on the cookie name or name and value. Useful if the site caches responses separately based on the presence of a cookie. For example, a cookie that identifies the language of the end client might be used to separate English content from French content in cache. Using this match, you would be able to invali-date one set of content without invalidating the other set.

cpcode-range Matches a CP-code or range of codes. Useful if the site uses multiple CP-codes to segre-gate content.

arl-type Matches on the type of the ARL (edge server configuration or FreeFlow).

request-header See Caution belowa. Matches on the name or name and value of the header. Useful for matching on the Host: in the request if many hostnames are served from a single origin site and the contents are cached separately based on hostname. This is useful when a client header is included in the Cache Key using the Force CacheID feature.

request-type Matches on the source of the request (end user versus ESI processor, for example.) This is not generally a useful distinction for invalidations.

method Matches on the method of the request. Method is a component of the cache key by default. This is useful if POST responses are being cached and you want to distinguish between POST and GET in your invalidation request.

protocol Matches on the protocol (HTTP vs. HTTPS). Protocol is a component of the cache key by default, so this match is useful for invalidating one set of content but not the other.

query-string See Caution belowa. Matches on the name or name and value of a query string argu-ment. Useful if query arguments are being used to distinguish objects in cache by including the arguments in the cache key.

typecode Matches on the typecode of the request v1 ARL. May be useful if you want to invalidate FreeFlow request objects that use a particular typecode. For example, all requests that use an Object ID under typecode 7.

response property

response-header

See Caution belowa. Matches on header name or name and value. Useful if a custom identifier is used to tag content. It is then possible to invalidate the content that con-tains the custom identifier rather than identify the content by other properties.



Path Matches The <match> tags listed in this section are used to describe the URL path. These tags are sometimes referred to as URL component matches. They create “nodes” in the metadata file and assist in the efficient application of metadata to requests.

The path match tags and their meanings, which are discussed in detail in the subse-quent section of this chapter, are:

recursive-dirs value="path component": match the specified directory and all its suddirectories

sub-dirs-only: match all directories nested within the current directory, but not the current directory

this-dir: match the current directory, but not its subdirectories

filename value="filename.ext": match an exact file within the current directory

filename value="No File Specified": match the default file within the current directory

URL Components Must be Nested with Each Other and not with Other Match Types

You cannot nest URL component matches within any other match type. That is, these matches are used to describe the URL and must be nested within one another in an unbroken fashion to form the URL path in its proper order. For example, you can-not nest a “recursive-dirs” match inside a “cookie” match, because the cookie is not a component of the URL. And you must list the components in the correct order, so you cannot enclose a “recursive-dirs” match within a “filename” match, because the filename is always last in the URL.

Wildcards and Regular Expressions Are Not Supported

There is currently no support for wildcards (for example, *) or regular expression matching syntax in path matches. However, see the sub-dirs-only match, for a special case of declaring a path indirectly.

recursive-dirs The recursive-dirs match is used to match against a particular path component (directory) and any subdirectories of that path component. If you don’t want to match recursively, you would pair this match with a this-dir match, as explained below. The syntax for this path match is:

<match:recursive-dirs value="dir" nocase="off" include-path-params="off"></match:recursive-dirs>

The value attribute is the directory name without the leading or following slash (/).

The nocase attribute is a Boolean to specify whether or not the match should be case-sensitive. A setting of “on” makes the match case-insensitive. The default is “off.”

The “include-path-params” attribute is a Boolean to specify whether path param-eters should be considered when matching on a path component. By default, the flag is off and the path parameters are ignored during the comparison.

Notice that the match is for a single component of the URI path. You must not com-bine path components to match a longer portion of the URI path.


Match Tags

That is, the following syntax is not allowed:

<match:recursive-dirs value="images/borders">

Although the match value is a single component of the URI path, this does not mean that the component can exist anywhere in the URI and result in a match. A more complete metadata example would look something like this:

<eccu><match:recursive-dirs value="images">

<revalidate>1046581729</revalidate></match:recursive-dirs>

<eccu>...

In the example above the match tag <match:recursive-dirs value="images"> is at the root directory. This match applies to any files that match the URI paths:

www.example.com/images/www.example.com/images/*/www.example.com/images/*/*/...

Note that it does not apply the revalidate metadata to:

www.example.com/electronics/images/

The metadata example could be expanded to include another subdirectory, which would be specified with a separate tag. The relevant portion of the metadata would look like the following:

<match:recursive-dirs value="images"><match:recursive-dirs value="borders">



The example above applies the <revalidate> tag to all files that match the URI path:

www.example.com/images/borders/www.example.com/images/borders/*/...

sub-dirs-only The syntax for this path match is:

<match:sub-dirs-only value="Sub-directories Only"></match:sub-dirs-only>

This match is used to set metadata for all directories beneath the current directory, but not the current directory. In most cases you will first declare the directory in a separate recursive-dirs match. The exception is when you mean to match on any directory below the root directory.

The following metadata example sets revalidation for all files in any subdirectory of the “images” directory, but not the images directory itself.

<match:recursive-dirs name="images"><match:sub-dirs-only" value="Sub-directories Only>





Nesting sub-dirs-only Matches

It is also possible, though not recommended, to nest sub-dirs-only tags within each other to specify a path that contains no specific component names.

Specifically, you could match any files in directories three levels deep and below, such as these:

www.example.com/anydir/anydir2/anydir3/www.example.com/images/borders/specials/

and apply <revalidate> with the following metadata:

<match:sub-dirs-only value="Sub-directories Only"><match:sub-dirs-only value="Sub-directories Only">

<match:sub-dirs-only value="Sub-directories Only"><revalidate>1046581729</revalidate>

</match:sub-dirs-only></match:sub-dirs-only>

</match:sub-dirs-only>

Notice that in no case was a directory component specified by name. In this sense, “sub-dirs-only” matches can be interpreted as “*”.

this-dir This-dir matches restrict the application of metadata to the current path component match rather than applying the metadata to all subdirectories.

The syntax for this path match is:

<match:this-dir value="This Directory Only"></match:this-dir>

The following metadata example sets revalidation for the images directory but not for any subdirectory of the images directory.

<match:recursive-dirs value="images"><match:this-dir value="This Directory Only">

<revalidate>1046581729</revalidate></match:this-dir>


filename It is possible to match either a specific file or the default file within a directory. The metadata tags are:

filename value="filename.ext": match an exact file within the current directory

filename value="No File Specified": match the default file within the current directory

Match a Specific File To match a specific filename, the syntax is:

<match:filename value="file.ext" nocase="off" include-path-params="off"></match:filename>

The value attribute takes a string that is the exact filename to match.

The nocase attribute is a Boolean to specify whether or not the match should be case-sensitive. A setting of “on” makes the match case-insensitive. The default is “off.”


Match Tags

The include-path-params attribute is a Boolean to specify whether or not the match should consider the path parameter as part of the string to match. The default is “off.”

The following metadata example matches the index.html file in the root directory of a domain only.

<match:this-dir value="This Directory Only"> <match:filename value="index.html">

<revalidate>1046581729</revalidate> </match:filename> </match:this-dir>

Matching the DefaultFile

You can match the default file within a single directory using a special value for the filename match. The syntax is:

<match:filename value="No File Specified"></match:filename>

“No File Specified” is a literal string used as the match value, because it is unlikely anyone would have an existing file with this name. This value instructs the Akamai server to apply metadata to whatever file the origin server would deliver as the default if the directory were accessed without specifying a file. This is handy because not all default files are .html.

Request Property Matches

These match tags evaluate some property of the request and apply metadata to the request when the match evaluates to true. For example, you can apply metadata based on whether or not the request headers include a particular cookie with a particular value.

ext Matches the file extension in the request URL. This particular match type is not case sensitive; that is, listing “gif ” as the extension to match will also match extensions “GIF” “Gif ” “giF” etc.

The following example metadata revalidates all files with the extension .exe.

<match:ext value="exe"><revalidate>1046581729</revalidate>

</match:ext>

The value argument accepts a space-separated list of strings that are the file extensions to match. Again, this match is not case sensitive.

Note that this match is applied correctly in cases where the request URL includes a query string. Given the example above, http://www.example.com/sample.exe?id=375 would match the extension “exe”. The extension is everything between the final dot (.) in the last path segment and the end of the URL, the beginning of the query string (if present), or beginning of parameters (if present). Parameters are separated from the extension by a semicolon (;) and may contain variable=value settings.

cookie This match type matches on cookies received from the client (browser) in the Cookie header. The syntax for this match type is:



<match:cookie name="user_id" op="present" value="">

Match tag properties for match:cookie are:

name: name of the cookie

The name attribute of this match type allows for wildcard characters (*) that will match any character in a cookie name. In this feature, the wildcard will be “non-greedy” and will match zero or more characters. This was introduced in 4.4. Exam-ples:

*sessionid* matches: sessionid, xxsessionid, sessionidyy, xxsessionidyy, etc.

*sessionid matches: sessionid and xxsessionid but not sessionidyy or xxsession-idyy.

sessionid* matches: sessionid and sessionidyy but not xxsessionid or xxsession-idyy.

* matches all cookie names.

*a*a*a* matches a cookie name that has three letter 'a's anywhere in it.

If only one wildcard is used in a name and it's the last character, it would be equiva-lent to setting the name-prefix-match property to on and not using the wildcard character. In order to avoid any conflicts between name-prefix-match and the new wildcard support, the Akamai edge server will ignore the special meaning of wildcards in the cookie name when name-prefix-match is on and translate them literally as it does now (again, this is for backward compatibility).

Given that browsers don't enforce any standards for cookie names, it's possible for sites to use the wildcard character as part of the name, however that's very unlikely. In order to support this corner case, users can “escape” the wildcard by using a backslash in front of the wildcard to mean a literal wildcard. In turn, if the backslash is part of the cookie name (again, very unlikely), users will have to escape the backslash by another backslash. The purpose of the backslash is to force the edge server to translate the character following it literally. Examples:

sessionid\* matches “sessionid*” exactly.

sessionid\*\\ matches “sessionid*\” exactly.

sessionid\** would match a cookie name that begins with “sessionid*”.

sessioni\d would match “sessionid” exactly. Notice that this example escaped the letter 'd' which is not special. Akamai edge servers will allow for this in case a customer accidentally escapes a non-special character.

name-prefix-match: sets whether the string in “name” must match the cookie name exactly or be a prefix of the full cookie name. The property is a simple Boolean and defaults to “off ”. This is particularly useful for matching “sessionid” cookies, where the cookie name includes a unique string but has a constant prefix.

value: The full or partial value the cookie should have.

op: Match operation. Must be one of the following:


Match Tags

present: The given cookie name must be present in the HTTP headers.

missing: The given cookie name must not be present in the HTTP headers.

strcmp: The cookie must have exactly the given value.

strcasecmp: Same as strcmp but not case sensitive.

strstr: The cookie must have the given sub string (specified as the value).

strcasestr: same as strstr but not case sensitive.

Examples Match only if a cookie named “session_id” exists:

<match:cookie name="session_id" op="present" value="">

Match only if a cookie named “user_id” doesn't exist:

<match:cookie name="user_id" op="missing" value="">

Match only if a cookie named “logged_in” is set to “yes”:

<match:cookie name="logged_in" op="strcmp" value="yes">

Same thing matching “yes” case insensitively:

<match:cookie name="logged_in" op="strcasecmp" value="yes">

Match only if a cookie named “cust_type” has “_vip_” somewhere within it:

<match:cookie name="cust_type" op="strstr" value="_vip_">

Same thing matching “_vip_” case insensitively:

<match:cookie name="cust_type" op="strcasestr" value="_vip_">

Using SpecialCharacters

If special characters are included in the value field, they must be embedded in exactly the way the origin server embeds them. For example, the space is considered a special character in cookie values. If the origin server escapes it with %20, it must be escaped with %20 in the value field. If the origin server doesn't escape it, it should not be escaped. The problem is that browsers don't enforce escaping. How a value appears in the request header really depends on how the origin server created it.

cpcode-range This match type matches on the content provider code (Billing Code). This match is useful primarily in cases where a content provider has more than one CP code.

The current syntax is:

<match:cpcode-range value="50-55"></match:cpcode-range>

When the match tag contains ranges, the starting and ending ranges are separated by a dash '-' and different ranges are separated by a space. Here's an example:

<match:cpcode-range value="1-101 5381-5500 8000-8999"></match:cpcode-range>

You can also specify a single number if there's no range:

<match:cpcode-range value="5381 5383 8000-8999 9001"></match:cpcode-range>



You can specify a range to include all numbers after a particular number by listing an open-ended range, like this:

<match:cpcode-range value="5000-">

arltype This match type matches on the format of the request ARL (Akamai Resource Loca-tor). The syntax for this tag is:

<match:arltype value="v1-arl">

Possible values are “v1-arl”, “transparent”, “prepend”.

v1-arl – applies to any ARL that uses Typecodes. These are ARL’s used by the FreeFlow service and generally look like this example:

http://a123.g.akamai.net/7/123/456/e358f5de00e9/www.example.com/logo.gif

prepend – applies to ARL's that use an ARL token but not a Typecode. The ARL token is generally the same as the hostname in the Absolute URL portion of an ARL. When it is an ARL token, this field can be any string; it doesn’t have to conform to the format of a hostname.

transparent – is any ARL (actually a URL) that isn't one of the other two. It is called “transparent” because it generally looks like a simple URL. This is the for-mat generally used with Akamai edge server configurations.

Example:

The following metadata revalidate any requests that come in the form of a v1-ARL.

<match:arltype value="v1-arl"> <revalidate>1046581729</revalidate>

</match:arltype>

request-header This match type matches on the presence of a particular header or the contents of a header in the client request. The syntax for this tag is:

<match:request-header operation="operation" argument1="string" argument2="string">

A specific example would be:

<match:request-header operation="name-value-strcasestr" argument1="Referer" argument2=".domain.com">

This the request-header tag includes an “operation” to specify what information to look for in the header. The possible values for the operation tag are:

multiple-hostsstrstrstrcasestrname-presentname-value-cmpname-value-casecmpname-value-strstrname-value-strcasestrregex

Each of these operations is described below with examples.


Match Tags

Negative Matching

Each of these match operations can be performed as a “negative match.” That is, the match is successful if the conditions specified are not met. The syntax for the negative match is formed by inserting an exclamation mark '!' before the operation name.

For example:

<match:request-header operation="!name-present" header-name="Referer">

This will cause the match to be evaluated to true if the given header name is not present.

Special Case for Name-Value Matches

There's a special rule for the “name-value” functions for cases where the given header name occurs multiple times in the request header. If the function is not being negated, the match will evaluate to true if the given header value matches the value of any of the headers. If the function is being negated, the match will only evaluate to true if none of the values of the incoming header match the one specified in meta-data.

multiple-hosts Matches requests whose header contains more than one Host header.

<match:request-header operation="multiple-hosts">

For operation="multiple-hosts", argument1 and argument2 are ignored and can be left out or included without affecting edge server behavior.

!multiple-hosts matches if the request has no Host header or has just one Host header.

strstr This match value requires an “argument1” property, which is a substring to match anywhere in the entire request headers. The match is case-sensitive

<match:request-header operation="strstr" argument1="abc">

Argument2 is ignored and can be left out or included without affecting edge server behavior.

!strstr: matches if the given substring is not in the header.

strcasestr Same as strstr except that it's not case sensitive.

<match:request-header operation="strcasestr" argument1="abc">


!strcasestr matches if the given substring is not in the header. The match is not case sensitive.

name-present This operation matches requests that contain the given request header. This match is not case sensitive. Argument1 specifies the header name.

<match:request-header operation="name-present" argument1="Referer">




!name-present matches if the given header name is not part of the request headers.

name-value-cmp Matches requests where a request header with a specified name (argument1) matches the given header-value (argument2). The match must be exact, rather than a sub-string of the header value. The match is case sensitive.

<match:request-header operation="name-value-cmp" argument1="User-Agent" argument2="Custom Agent">

!name-value-cmp matches if either the given header name is not present or its value doesn't match the one specified in metadata.

name-value-casecmp This match functions like name-value-cmp except that the match is not case sensi-tive.

<match:request-header operation="name-value-casecmp" argument1="user-agent" argument2="custom-agent">

!name-value-casecmp: matches if either the given header name is not present or its value doesn't match the one specified in metadata. The match is not case sensitive.

name-value-strstr This operation matches requests where the specified header (argument1) contains the given sub-string (argument2)somewhere in its value. The match is case sensitive.

<match:request-header operation="name-value-strstr" argument1="Referer" argument2=".domain.com">

!name-value-strstr: matches if either the given header name is not present or the sub-string specified in metadata is not part of the header's value.

name-value-strcasestr Same as name-value-strstr above except that the match is not case sensitive.

<match:request-header operation="name-value-strcasestr" argument1="Referer" argument2=".domain.com">

!name-value-strcasestr: matches if either the given header name is not present or the sub-string specified in metadata is not part of the header's value. The match is not case-sensitive.

regex Matches on a regular expression pattern using extended regular expressions

For example:

<match:request-header operation="regex" argument1="ab[cd]">

request-type This matches on the type of request the Akamai server receives. Possible values for the tag are: 'user,' 'esi-fragment,' 'esi-war,' and 'esi-tunnel.'

<match:request-type value="esi-fragment"></match:request-type>

esi-fragment matches on fragment requests going from ESI->edge server->origin and back from origin->edge server->ESI.

esi-war matches on WAR requests going from ESI->edge server->origin and back from origin->edge server->ESI.


Match Tags

esi-tunnel matches on request-mod (EdgeJava) requests going from ESI->edge server->ej-tomcat and back from ej-tomcat->edge server->user. It's used to for-ward requests to the local Java app server. This is the only request-type that's not applicable to cacheh since all request-mod requests go to the local Java app server.

user matches everything else. This maintains backward compatibility with the esi-fragment match type, which matched on whether a request was for a frag-ment, or not for a fragment. User registers a positive match if the request is not any of the other types (esi-fragment, esi-war, esi-tunnel).

The edge server allows multiple values for the request-type match with a comma sep-arator to indicate that the match should evaluate to true if any of the request types match, for example:

<match:request-type value="user,esi-tunnel,esi-war">

The old match type <match:esi-fragment value="on|off"> was adjusted for backward compatibility so that the 'on' setting is the same as <match:request-type value="esi-fragment"> and the 'off' setting is the same as <match:request-type value="user">

method This match type allows for application of metadata based on the method used in the request (GET, POST, HEAD and any others recognized by Akamai edge servers). The match is case insensitive.

<match:method value="pOsT"><revalidate>1046581729</revalidate>

</match:method>

protocol This tag matches on the protocol used in the incoming request.

<match:protocol value="HTTPS"><revalidate>1046581729</revalidate>

</match:protocol>

Acceptable values are “HTTPS” or “HTTP”. When the client connects through SSL HTTPS produces a match, otherwise HTTP is a match.

query-string This tag matches on an argument in the query string with functionality similar to what is available for matching on cookies. The tag can match for whether the query string argument:

• is either present or missing

• has or doesn't have a particular value

• has or doesn't have a particular sub string inside it

The matching functions can be specified as either case sensitive or case insensitive.

The metadata tag is:

<match:query-string name=”arg-name” name-prefix-match=”off” op=”operation-type”>

The properties are as follows:

name: Contains the name of the argument in the query string to match against. (the edge server looks for this name in the query string using a case sensitive match).



name-prefix-match: This is a flag that indicates whether the parameter name given (above) is just a prefix. The default is off.

op: Indicates the match operation to perform. It has to be one of the following five values. Each of these can be testing for the negative by preceding the op name with an exclamation point (for example, “!name-present”)

name-present: to check whether given parameter name is present

strcmp: The given parameter contains the given value.

strcasecmp: Same as strcmp but not case sensitive.

strstr: The given parameter contains the given sub string.

strcasestr: same as strstr but not case sensitive.

wildcard: case sensitive match where “*” represents zero or more characters and “?” represents one character.

wildcardcase: same as wildcard but not case sensitive

value: Contains the value/sub-string to match against. (Note: if you want to match against the absence of a value, the edge server will accept value="" and perform the match correctly. However, in version 4.3, MUI will not permit this syntax, so you need to enter it by hand. This limitation will be addressed in ver-sion 4.4)

unescape: Indicates how to unescape the query parameter's value before the match operation:

none: the query string value will be compared as is (this is the default)

url-unescape: the query string value will be url unescaped before the comparison

Examples

Check whether the “sessionid” query string parameter is present:

<match:query-string op="name-present" name="sessionid">

Check whether the “sessionid” query string parameter is missing:

<match:query-string op="!name-present" name="sessionid">

Check whether the “account” query string parameter contains the value “valid” (case insensitively):

<match:query-string op="strcasecmp" name="account" value="valid">

Check whether the “account” query string parameter contains a value other than “valid” (case sensitively):

<match:query-string op="!strcmp" name="account" value="valid">

Check whether the “product_name” query string parameter contains the word “com-puter” anywhere inside it (case sensitively):

<match:query-string op="strstr" name="product_name" value="computer">


Match Tags

Check whether the “product_name” query string parameter doesn't contain the word “computer” (case sensitively):

<match:query-string op="!strstr" name="product_name" value="computer">

typecode This match tag makes it possible to apply metadata to v1 ARL requests with a partic-ular typecode. The value of the tag is a space-separated list of typecode characters.

<match:typecode value="5 7"> ...</match:typecode>

Response Property Matches

response-header This match tag matches on characteristics of the response header. In specific, this tag was implemented to facilitate matching on MIME type and HTTP Reply Status code.

The syntax for the tag is:

<match:response-header operation="enum" argument1="headername or status-code" argument2="string">

</match:response-header>

The functionality of this match type is very similar to the request-header match type. Like the request-header match, the response header match has three properties:

operation: Describes the type of matching to perform. All operations, except the numeric comparisons, can be negated by prefixing them with an exclamation point “!”. Possible values are:

status: Match on the response status code

name-present: Checks whether the given header name is present in the request.

name-value-cmp: Checks whether the contents of the given header matches the given value case sensitively.

name-value-casecmp: Same as name-value-cmp except it's case insensitive

name-value-strstr: Checks whether the contents of the given header contains the given substring case sensitively.

name-value-strcasestr: Same as name-value-strstr except it's case insensitive

name-value-num-eq: (numeric comparison: ==) Checks whether the contents of the given header is numeric and whether it is equal to the given value.

name-value-num-ne: (numeric comparison: !=)

name-value-num-lt: (numeric comparison: <)

name-value-num-le: (numeric comparison: <=)

name-value-num-gt: (numeric comparison: >)

name-value-num-ge: (numeric comparison: >=)



argument1: contains the header-name to match against for all operations except 'status'. For 'status', it has to be a status code (or list/range of codes) to match against. The range can be specified in the same syntax used by the cpcode-range match tag.

argument2: contains the value to match against for all operations except 'status'.For the numeric operators, only integer values are considered. If the header's value is not numeric, the comparison won't be executed. The value supplied by the user (in argument2) is on the right and the value from the response header is on the left of the operator:

header-value (==,!=,<,<=,>,>=) user-supplied-value

The largest number that the edge server can handle in this comparison is (231 - 1) or (2147483647).

Examples:

The following example would require revalidation of any object that contained the HTTP header “Custom-Identifier” with a value of “a2f9e724”. A scheme of this nature might be useful for forcing revalidation of all files that are related. This rela-tionship would be expressed by the value of the Custom-Identifier.

<match:response-header operation="name-value-cmp" argument1="Custom-Identifier" argument2="a2f9e724">

<revalidate>1046581729</revalidate></match:response-header>


content control interfaces

Documents