Velir / akamai-ccu-rest-api-connector

15 stars 12 forks source link

Velir Akamai CCU REST connector for AEM (CQ)

Description

This bundle provides a "ready to use" OSGI connector for the Akamai Open CCU V3 REST API. This connector has been written in groovy using the http-builder framework. It is designed to enable cache invalidation for AEM/CQ CMS when assets get invalidated. It can be easily configured with your own credentials and settings. The connector provides all services that you can request via the REST API as well as convinence

The bundle is made to be as light as possible and can be installed just by itself. You will need groovy-all version 2.4.7 to be installed along with some others bundles like httpclient, commons-collections, commons-lang ... but they usually are already there.

As of version 2.5, this bundle requires AEM 6.3+

Implementation

There are three major classes that manage the invalidation :

def response = ccuManager.fastPurgeByUrls(["http://www.mysite.com/test", "http://www.mysite.com/test2"])
response = ccuManager.fastPurgeByCpCode("CPCODE1")
response = ccuManager.fastPurge(["http://www.mysite.com/test", "http://www.mysite.com/test2"], PurgeType.ARL, PurgeAction.REMOVE, PurgeDomain.PRODUCTION)
response = ccuManager.fastPurgeByTags(['tag1', 'tag2'])
response = ccuManager.fastPurge(["http://www.mysite.com/test", "http://www.mysite.com/test2"], FastPurgeType.URL, PurgeAction.INVALIDATE, PurgeDomain.STAGING)
response = ccuManager.fastPurge(["http://www.mysite.com/test", "http://www.mysite.com/test2"], FastPurgeType.URL)
response = ccuManager.fastPurge(["CPCODE1"], FastPurgeType.CPCODE)
response = ccuManager.fastPurge(["tag1"], FastPurgeType.TAG)

The minimum configuration needed for that service are your Akamai API tokens and secret.

You don't have to use the whole thing -- you could easily just use the CCuManager to invalidate your cache without using the listener.

Configuration

Each of these classes can be configured to fit you need and your Akamai credentials. In your JCR repository under /apps/your_app/config.author/ you can add the following configuration files:

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    rootCcuUrl="https://api.ccu.akamai.com"
    clientToken="your_clientSecret"
    clientSecret="your_clientSecret"
    accessToken="your_accessToken"
    defaultPurgeAction="remove"
    defaultPurgeDomain="production"
    threadPoolSize="5"/>

For more info on credentials see https://developer.akamai.com/introduction/Prov_Creds.html

defaultPurgeAction : The default purge if not specified.

defaultPurgeDomain : The default domain if not specified.

threadPoolSize : Number of threads to dedicate to the API HTTP Client. Defaults to 5.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    pathsHandled="[/content/dam]"/>

pathsHandled: Comma separated list of paths that can be invalidated.

<?xml version="1.0" encoding="UTF-8"?>
<jcr:root xmlns:sling="http://sling.apache.org/jcr/sling/1.0" xmlns:jcr="http://www.jcp.org/jcr/1.0"
    jcr:primaryType="sling:OsgiConfig"
    rootSiteUrl="http://www.mysite.com"/>

rootSiteUrl: The root site url that is prepended to the path being invalidated.

Administration Page

We've included a small administration page that can be found in the Velir section on AEM Tools. Example localhost direct url: http://localhost:4502/etc/velir/akamaiflush.html

This page is simple and allows administrators to manually flush urls without a replication event. Use cases for this would be after a deployment or in an emergency where needed production objects are stale in the CDN. The benefit of this page, is that AEM administrators can access this functionality without having to be provided access the Luna control center.

The admin page can be filled in manually with URLS/ARLs, tags or CP codes and is currently limited to one object type per request.

Also, you can load the form via json file on the 'Choose json flush file' button. This takes in a json file in the following format, specifying objects and object type.

{
    "objects":[
        "https://www.velir.com/object1",
        "https://www.velir.com/object2"
    ],
    "type" : "URL"
}

Type is optional, but can be values URL, CPCODE or TAG.

This option can be used if there is a repeatable series of objects that might need regular flushing, such as in after deployments.

Administration Security

It is recommended to limit the usage of the akamai flush administration page and endpoint to approved users. This is to limit usage to users who know what they are doing and are authorized to do so. First, you can deny access to the admin page itself, /etc/velir/akamaiflush, which should be blocked for most user groups by default in newer versions of AEM. Secondly, it is highly recommended to configure the API endpoint servlet to do the same.

Who are we

Velir is a Web Agency that provides a large scale of expertise in user experience design, content management, and marketing platform integrations. Our clients partner with us to develop and implement websites and applications powered by Sitecore and AEM/Adobe CQ. More on www.velir.com

License

This project is open source under MIT License.

More information

If you want to learn more about the CCU REST API: https://developer.akamai.com/introduction/