AkamaiApi

Now with CCU REST support!

AkamaiApi is a ruby library and command line utility to interact with Akamai CCU (Content Control Utility) and ECCU (Enhanced Content Control Utility) services.

Using the CLI

After gem installation you will have a CLI utility to execute operations on Akamai. Each method requires authentication. You can provide auth info using one of the following methods:

Passing --username (-u) and --password (-p) arguments at each invocation (for ECCU/old CCU Rest Api)
Creating a config file in your HOME directory named .akamai_api.yml with the following format:

    auth:
      - user
      - pass
    openapi: # openapi credentials
        base_url: https://akab-abcdefghi-jklmnopq.purge.akamaiapis.net
        client_token: akab-abcdefghijklmnopqrstuv12345
        client_secret: abcedfhijklmnopqrstuv12345
        access_token: akab-12345abcedfghijklmnopqrstuv
    log: true # optional for enabling logging in ECCU requests. false by default

Tasks

When using the CLI you can work with both CCU and ECCU.

    akamai_api CCU          # CCU Interface
    akamai_api ECCU         # ECCU Interface
    akamai_api help [TASK]  # Describe available tasks or one specific task

Use akamai_api help to view the help of the CLI.

CCU

In the CCU interface you can work with CP Codes and ARLs.

    akamai_api CCU cpcode                 # CP Code CCU actions
    akamai_api CCU help [COMMAND]         # Describe subcommands or one specific subcommand
    akamai_api CCU arl                    # ARL CCU actions
    akamai_api CCU status [progress_uri]  # Show the CCU queue status if no progress_uri is given, or show a CCU Purge request status if a progress uri is given

CP Code

    akamai_api CCU cpcode help [COMMAND]                  # Describe subcommands or one specific subcommand
    akamai_api CCU cpcode invalidate CPCODE1 CPCODE2 ...  # Purge CP Code(s) marking their cache as expired
    akamai_api CCU cpcode remove CPCODE1 CPCODE2 ...      # Purge CP Code(s) removing them from the cache

When removing or invalidating a CP Code you can provide the following optional arguments:

--domain, -d: Specify if you want to work with production or staging. This is a completely optional argument and usually you don't need to set it.

ARL

  akamai_api CCU arl help [COMMAND]                                                   # Describe subcommands or one specific subcommand
  akamai_api CCU arl invalidate http://john.com/a.txt http://www.smith.com/b.txt ...  # Purge ARL(s) marking their cache as expired
  akamai_api CCU arl remove http://john.com/a.txt http://www.smith.com/b.txt ...      # Purge ARL(s) removing them from the cache

When removing or invalidating an ARL you can provide the following optional arguments:

--domain, -d: Specify if you want to work with production or staging. This is a completely optional argument and usually you don't need to set it.

Status

If you don't provide a progress_uri this command will print the CCU queue status. E.g.

$ akamai_api CCU status
------------
Status has been successfully received:
    * Result: 200 - The queue may take a minute to reflect new or removed requests.
    * Support ID: 12345678901234567890-123456789
    * Queue Length: 0
------------

When you provide a progress_uri or a purge_id this command will print the CCU request status. E.g.

$ akamai_api CCU status 12345678-1234-5678-1234-123456789012 # or you can pass /CCU/v2/purges/12345678-1234-5678-1234-123456789012
------------
Status has been successfully received:
    * Result: 200 - Done
    * Purge ID: 12345678-1234-5678-1234-123456789012 | Support ID: 12345678901234567890-123456789
    * Submitted by 'gawaine' on 2014-05-20 08:19:21 UTC
    * Completed on: 2014-05-20 08:22:20 UTC
------------

ECCU

In the ECCU interface you can see the requestes already published and publish your own requests.

    akamai_api ECCU help [COMMAND]                            # Describe subcommands or one specific subcommand
    akamai_api ECCU last_request                              # Print the last request made to ECCU
    akamai_api ECCU publish_xml path/to/request.xml john.com  # Publish a request made in XML for the specified Digital Property (usually the Host Header)
    akamai_api ECCU requests                                  # Print the list of the last requests made to ECCU
    akamai_api ECCU revalidate now jhon.com "*.png"           # Create an XML request based on querystring input (*.png) for the specified Digital Property (usually the Host Header)

Viewing Requests

You can see the requests published on ECCU using akamai_api ECCU requests For each request you will see all its details (code, status, etc.) except the file content. To view the file content add the --content (-c) option.

To see only the last request you can use akamai_api ECCU last_request.

Publishing Requests in XML

To publish requests made in XML (ECCU Request Format) you can use akamai_api ECCU publish_xml.

Usage:
  akamai_api publish_xml path/to/request.xml john.com

Options:
  -P, [--property-type=type]              # Type of enlisted properties
                                          # Default: hostheader
      [--no-exact-match]                  # Do not do an exact match on property names
  -e, [--emails=foo@foo.com bar@bar.com]  # Email(s) to use to send notification on status change
  -n, [--notes=NOTES]                     # Default: ECCU Request using AkamaiApi gem

The command takes two arguments:

the file containing the request;
the Digital Property to which you want to apply the request (usually it's the host);

Revalidate based on a query string

You con use akamai_api ECCU revalidate for generate an XML revalidation file base on a query string.

Usage:
  akamai_api revalidate now jhon.com "*.png"

Options:
  -f, [--force]                            # Force request without confirm
  -P, [--property-type=type]               # Type of enlisted properties
                                           # Default: hostheader
      [--no-exact-match]                   # Do not do an exact match on property names
  -e, [--emails=foo@foo.com bar@bar.com]   # Email(s) to use to send notification on status change
  -n, [--notes=NOTES]                      # Default: ECCU Request using AkamaiApi gem

The command produces the following result and ask you if you want to publish:

<?xml version="1.0"?><eccu><match:ext value="png"><revalidate>now</revalidate></match:ext></eccu>

The command takes two arguments:

the timestamp after which any content, matched, in cache with an older timestamp will be considered stale
the Digital Property to which you want to apply the request (usually it's the host);
the query string that will be analyzed to produce the XML

Rules for the Querystring

foo : indicate a filename
foo/ : indicate the foo dir
*foo/ : indicate all direct sub dirs of foo**
*foo/* : indicate recursively all sub dirs of foo**
*.png : indicate all pngs
foo.txt : indicate specific file (foo.txt)

Following the Akamai API docs there is a limitation:

Akamai recommends that you limit the number of matches to 250 or fewer. Submitting more than 250 invalidation requests at one time can result in a “global invalidation”

As a Library

Remember to init the AkamaiApi gem with your login credentials. You can set your credentials with the following statement:

AkamaiApi.config.merge! :auth => ['user', 'pass']

CpCode: model representing a CP Code. Use the ::all method to retrieve the list of available CpCode.
CCU : CCU interface. Use the ::purge method to purge a list of resources.
ECCURequest: model representing an ECCU request.

CCU

::status

When no argument is given, this command will return a AkamaiApi::CCU::Status::Response object describing the status of the Akamai CCU queue. E.g.

AkamaiApi::CCU.status
# => #<AkamaiApi::CCU::Status::Response:0x00000101167978 @raw={"supportId"=>"12345678901234567890-123456789", "httpStatus"=>200, "detail"=>"The queue may take a minute to reflect new or removed requests.", "queueLength"=>0}>

When you pass a progress_uri or a purge_id, this command will check the given Akamai CCU request. E.g.

AkamaiApi::CCU.status '/CCU/v2/purges/foobarbaz' # you can pass only 'foobarbaz' (the purge request id) as argument
# => #<AkamaiApi::CCU::PurgeStatus::SuccessfulResponse:0x000001014da088
#  @raw=
#   {"originalEstimatedSeconds"=>480,
#    "progressUri"=>"/CCU/v2/purges/12345678-1234-5678-1234-123456789012",
#    "originalQueueLength"=>6,
#    "purgeId"=>"12345678-1234-5678-1234-123456789012",
#    "supportId"=>"12345678901234567890-123456789",
#    "httpStatus"=>200,
#    "completionTime"=>"2014-02-19T22:16:20Z",
#    "submittedBy"=>"test1",
#    "purgeStatus"=>"In-Progress",
#    "submissionTime"=>"2014-02-19T21:16:20Z",
#    "pingAfterSeconds"=>60}>

It will return a AkamaiApi::CCU::PurgeStatus::SuccessfulResponse object when a purge request is found, or a Akamai::CCU::PurgeStatus::NotFoundResponse when no request can be found.

::purge

module AkamaiApi::CCU
  def purge action, type, items, args = {}
    ...
  end
end

action: symbol or string. It should be remove or invalidate. See the CLI documentation for more details
type: symbol or string. It should be arl or cpcode. Use arl to purge a list of urls, and cpcodes to purge a list of cp codes
items: the list of the resources to clean
args: additional options (domain)

It will return a AkamaiApi::CCU::Purge::Response object that you can use to retrieve the progress_uri (or the purge_id) of the request.

E.g.

AkamaiApi::CCU.purge :remove, :arl, ['http://www.foo.com/a.txt'], :domain => 'staging'
# => #<AkamaiApi::CCU::Purge::Response:0x00000101bf2848
#  @raw=
#   {"describedBy"=>"foo",
#    "title"=>"bar",
#    "pingAfterSeconds"=>100,
#    "purgeId"=>"1234",
#    "supportId"=>"130",
#    "detail"=>"baz",
#    "httpStatus"=>201,
#    "estimatedSeconds"=>90,
#    "progressUri"=>"/CCU/v2/purges/1234"}>

Purge Helpers

CCU = AkamaiApi::CCU

CCU.invalidate_cpcode cpcodes    # => wrapper to call .purge :invalidate, :cpcode
CCU.invalidate_arl arls          # => wrapper to call .purge :invalidate, :arl
CCU.invalidate :arl, arls        # => wrapper to call .purge :invalidate

CCU.remove_cpcodes cpcodes   # => wrapper to call .purge :remove, :cpcode
CCU.remove_arl arls          # => wrapper to call .purge :remove, :arl
CCU.remove :arl              # => wrapper to call .purge :remove

ECCURequest

An ECCURequest is an object representing an ECCU Request. To see all the published requests use the ::all method. To retrieve only the last request, you can use the ::last method. The following code should be self explaining about both class methods and instance methods:

    all_requests_ids = ECCURequest.all_ids                     # => Returns all available requests ids
    first_request    = ECCURequest.find all_requests_ids.first # => Return the ECCURequest model with the specified code

    all_requests = ECCURequest.all  # => Returns all available requests
    last_request = ECCURequest.last # => Return the last available request

    last_request.update_notes! 'My new note' # => Invoke the ECCU service to change the notes field
    last_request.update_email! 'foo@foo.com' # => Invoke the ECCU service to change the email to be notified on status change
    last_request.destroy                     # => Invoke the ECCU service to delete the request

Use the ::publish method to publish an ECCU Request:

    AkamaiApi::ECCURequest.publish 'example.com', my_content, args
    AkamaiApi::ECCURequest.publish_file 'example.com', 'path/to/file.xml', args

You can specify the following optional arguments in args: file_name, notes, version, emails, property_type, property_exact_match

Contributing

Clone this repository
Run 'bundle install'
Run specs using guard. Alternatively you can execute the specs with thor spec and cucumber features with cucumber

mikamai / akamai_api

readme