Akamai Diversity
Home > Akamai Japan > Akamai {OPEN} API を使用したキャッシュ削除

Akamai {OPEN} API を使用したキャッシュ削除

Akamaiの設定を外部アプリケーションから行うために、{OPEN} API と呼ばれるAPIが公開されています。

この記事では、お問合せの多い {OPEN} API を使用したキャッシュのクリアについて解説します。

1. Akamai {OPEN} APIとは

AkamaiのLUNAポータル画面から設定できる殆どの機能は「{OPEN} API」と呼ばれる、HTTPリクエストを使用して操作可能になっています。Akamai の {OPEN} API の仕様については以下のサイトに集約されています。

  • API Catalog
  • openapiscreenshot.png

    またAPI の実装方法について質問できる、以下のコミニティのグループが作成されています。

  • {OPEN} Developer Community | Akamai Community

  • community.png

    この記事では、問い合わせの多い Purge用のAPI について解説します。Purge用のAPIについてのドキュメントは以下のリンク先にあります。

  • The CCU API

  • Purge用APIの正式名は、CCU(Contents Control Utility)と呼ばれるAPIで、この記事の作成時点では version 2が最新です。

    また、HTTPリクエストなので言語には依存しませんが、この記事ではPythonを使用して、実際に簡単なPurgeリクエストを使ってみるまでを解説します。

    2. 認証・許可情報の作成

    2017/08/04追記:LUNAのインターフェイスのアップデートにより、記事作成時とLUNAの操作方法が変わっていますのでご注意下さい。

    {OPEN} API を使ったアクセスをできるようにするには、まずLUNA側に権限の追加を行います。

    「設定」→「APIの管理」「Luna APIs」→「新規コレクションの追加」を選びます

    以下 GUI での操作になりますので、キャプチャー画像でまとめました。画像はクリックで拡大します

    STEP1

    認証許可1.jpg

    STEP2

    認証許可2.jpg

    STEP3

    認証許可3.jpg

    STEP4

    ここまでの手順で、「ベースURL」「アクセストークン」「クライアントトークン」「クライアント秘密鍵」などの情報が生成されます。

    後で必要になるので、テキスト等にまとめておくと良いでしょう。

    認証許可4.jpg

    LUNA側で必要な設定をし、「ベースURL」「アクセストークン」「クライアントトークン」「クライアント秘密鍵」の情報が集まったら、いよいよAPIを呼び出すためのスクリプトの作成に入ります。

    3. ツール 「AkamaiOPEN-edgegrid-python」のインストール

    Python環境で{OPEN} API を使ったAuthorizationヘッダーの生成を簡素化するための「AkamaiOPEN-edgegrid-python」と言うツールがGitHubで公開されています。

    もちろん、このツールがなくても{OPEN}APIは使用できますが、ここでは説明を簡略化するために GitHub で公開されているこの「AkamaiOPEN-edgegrid-python」をダウンロードして使用します。ここではPython用のツールを使用しますが、他の言語用のツールも用意されています。

    このツールでは、HTTPリクエスト内に含まれる Authorizationヘッダーを、ツールに含まれている「EdgeGridAuth」クラスを使って生成しています。このクラスの定義は、Pythonの場合は

    <インストールディレクトリ>/AkamaiOPEN-edgegrid-python/akamai/edgegrid/edgerid.py

    に含まれています。詳細を知りたい方は、ソースコードを参照するか、こちらのドキュメントもあわせてご参照下さい。

    Authorizationヘッダーの情報の中にはタイムスタンプの情報も含まれており、APIを実行するクライアントの時間が大きくずれている場合はエラーとなり、リクエストの情報が盗まれた場合でも再利用を防ぐ仕組みになっています。リクエストの時間が検査されているため、クライアント側の時間は、NTPと同期させておくと安全です。また、リクエストの再実行を防ぐという点では、GUIDをHTTPヘッダーに含むことで、既に発行されたリクエストかどうかを確認する仕組みも実装されています。これらのHTTPヘッダーに付加される値の生成は「EdgeGridAuth」クラスの内部で行われており、この記事上のコードからは隠蔽されています。

    githubtool.png https://github.com/akamai-open/AkamaiOPEN-edgegrid-python

    上記のリンク先から Ptyhon 用のツールをダウンロードします

    [ec2-user@ip-172-31-12 ~]$ sudo git clone https://github.com/akamai-open/AkamaiOPEN-edgegrid-python
    Cloning into 'AkamaiOPEN-edgegrid-python'...
    remote: Counting objects: 224, done.
    remote: Total 224 (delta 0), reused 0 (delta 0), pack-reused 224
    Receiving objects: 100% (224/224), 46.65 KiB | 0 bytes/s, done.
    Resolving deltas: 100% (107/107), done.
    [ec2-user@ip-172-31-12 ~]$

    ダウンロードしたツールをセットアップします。

    [ec2-user@ip-172-31-12 ~]$ sudo easy_install pip
    Searching for pip
    Best match: pip 9.0.0
    Processing pip-9.0.0-py2.7.egg
    pip 9.0.0 is already the active version in easy-install.pth
    Installing pip script to /usr/bin
    Installing pip2.7 script to /usr/bin
    Installing pip2 script to /usr/bin
    Using /usr/lib/python2.7/site-packages/pip-9.0.0-py2.7.egg
    Processing dependencies for pip
    Finished processing dependencies for pip
    [ec2-user@ip-172-31-12 ~]$ which pip
    /usr/bin/pip
    [ec2-user@ip-172-31-12 ~]$ sudo pip install edgegrid-python

    Collecting edgegrid-python
    Downloading edgegrid-python-1.0.10.tar.gz
    Requirement already satisfied: requests>=2.3.0pyopenssl in /usr/lib/python2.7/site-packages (from edgegrid-python)
    Collecting ndg-httpsclient (from edgegrid-python)
    Downloading ndg_httpsclient-0.4.2.tar.gz
    Collecting pyasn1 (from edgegrid-python)
    Downloading pyasn1-0.1.9-py2.py3-none-any.whl
    Requirement already satisfied: urllib3 in /usr/lib/python2.7/site-packages (from edgegrid-python)
    Requirement already satisfied: PyOpenSSL in /usr/lib64/python2.7/site-packages (from ndg-httpsclient->edgegrid-python)
    Installing collected packages: ndg-httpsclient, pyasn1, edgegrid-python
    Running setup.py install for ndg-httpsclient ... done
    Running setup.py install for edgegrid-python ... done
    Successfully installed edgegrid-python-1.0.10 ndg-httpsclient-0.4.2 pyasn1-0.1.9
    [ec2-user@ip-172-31-12 ~]$

    こちらの「edgegrid-python」のセットアップ方法については、Githubの以下のリンク先の README.rst に記載されています。 https://github.com/akamai-open/AkamaiOPEN-edgegrid-python

    4. セットアップ確認用のスクリプトの作成

    セットアップの確認用に、以下のようなテストスクリプトを作ります。ここでは、test.py と名前を付けて保存します。

    ここでは、とりあえず環境のセットアップを確認するために、"現在溜まっているリクエストQUEUEの数を確認する"APIリクエストを作成しています。

    import requests
    from akamai.edgegrid import EdgeGridAuth
    from urlparse import urljoin
    baseurl = 'https://akab-3mmaadareregareqbl-eybzetlx6h7n3lyd.purge.akamaiapis.net/'
    s = requests.Session()
    s.auth = EdgeGridAuth(
    client_token='akab-3brdiu2qy2arerered3u-w4c3dqnnqpzxcrts',
    client_secret='4qSmEiJbkM2fuwsxDTEDNUM8XYwY9QIH6t8IDZ3DE=',
    access_token='akab-szimdreaw243854xud5qxszfjr3'
    )

    result = s.get(urljoin(baseurl, '/ccu/v2/queues/default'))
    print result.status_code

    ※1)緑色の字の部分は、LUNAで認証・許可情報を作成した時に出てきた値です。

    以下の様にスクリプトを実行し、200 が返ってきたら正しくセットアップされています。

    [ec2-user@ip-172-31-12 ~]$ python test.py
    200
    [ec2-user@ip-172-31-12 ~]$

    それ以外のステータスコードが返ってきた場合は、ステータスコード200がでるまでデバッグします。主なステータスコードとエラーの原因(の可能性)は以下になります。(HTTPステータスコードなので、これ以外のものが返ってくる事もあります)

    statuscode.png

    上記のステータスコード表は以下のリンクからの転載です。

  • Content Control Utility
  • ステータスコード 200が返って来る事が確認できたら、一歩進めて緑字の print文を以下のように加えて JSON の内容まで出力してみましょう。

    import requests
    from akamai.edgegrid import EdgeGridAuth
    from urlparse import urljoin
    baseurl = 'https://akab-3mmaadareregareqbl-eybzetlx6h7n3lyd.purge.akamaiapis.net/'
    s = requests.Session()
    s.auth = EdgeGridAuth(
    client_token='akab-3brdiu2qy2arerered3u-w4c3dqnnqpzxcrts',
    client_secret='4qSmEiJbkM2fuwsxDTEDNUM8XYwY9QIH6t8IDZ3DE=',
    access_token='akab-szimdreaw243854xud5qxszfjr3'
    )

    result = s.get(urljoin(baseurl, '/ccu/v2/queues/default'))
    print result.status_code
    print result.json()

    スクリプトを実行してみます。

    [ec2-user@ip-172-31-12 ~]$python test.py
    200
    {u'httpStatus': 200, u'detail': u'The queue may take a minute to reflect new or removed requests.', u'queueLength': 0, u'supportId': u'17QY14334659696709872-285689024'}
    [ec2-user@ip-172-31-12 ~]$

    200のステータスコードに加えて、JSON型式のデータが返ってきていれば、セットアップは完了です。実際のPurgeリクエストを実行するスクリプトを作成してみましょう。

    5. Purgeリクエストの実行

    以下のようなPurgeリクエストを作成します。名前は purge.py にしました。緑字の部分を以前のテスト用のスクリプトから変更しています。

    import requests
    import json
    from akamai.edgegrid import EdgeGridAuth
    from urlparse import urljoin
    baseurl = 'https://akab-3mmaadareregareqbl-eybzetlx6h7n3lyd.purge.akamaiapis.net/'
    s = requests.Session()
    s.auth = EdgeGridAuth(
    client_token='akab-3brdiu2qy2arerered3u-w4c3dqnnqpzxcrts',
    client_secret='4qSmEiJbkM2fuwsxDTEDNUM8XYwY9QIH6t8IDZ3DE=',
    access_token='akab-szimdreaw243854xud5qxszfjr3'
    )

    headers = {'Content-Type':'application/json'}
    data = {
    "type" : "arl",# URLの指定を使用
    "action" : "invalidate",# invalidate(無効化)
      "domain" : "production",# Production環境
    "objects" : [
    "https://www.yuhkih.site/images/lm55.jpg",# キャッシュの削除対象(※1)
    "https://www.yuhkih.site/index.html" # キャッシュの削除対象(※1)
    ]
    }
    result = s.post(urljoin(baseurl,'/ccu/v2/queues/default'),headers=headers,data=json.dumps(data)) #(※2)
    print result.status_code
    print json.dumps(result.json(),indent=2) #(※3)

    (※1)この記事作成時点では、キャッシュの削除対象は個別のURLを指定する必要があります。もしくは、特定のトラフィックをまとめる概念である"CPコード"単位でもキャッシュを削除できます。現時点でワイルドカードなどで削除する方式はサポートされていません。
    (※2)Purgeリクエストは POST リクエストになっている事に注意します。
    (※3)JSONの出力フォーマットを整形してdumpsするようにしてみました。

    スクリプトを実行します。以下のように 201 が返ってくれば、リクエストは成功です。

    [ec2-user@ip-172-31-12 ~]$python purge.py
    201
    {
    "estimatedSeconds": 240,
    "progressUri": "/ccu/v2/purges/74087c05-a25f-11e6-b019-fbc47af7a6cd",
    "supportId": "17PY1478244153365887-193369280",
    "httpStatus": 201,
    "detail": "Request accepted.",
    "purgeId": "74087c05-a25f-11e6-b019-fbc47af7a6cd", # (※1)
    "pingAfterSeconds": 240
    }
    [ec2-user@ip-172-31-12 ~]$

    (※1)この値は次のPurgeリクエストの進捗確認で使用します。

    補則

    Purge対象として指定できる data のフォーマットやパラメーターの基本形は以下のようになっています。

    "type":"arl" or "cpcode"  # URL(ARL)指定 or CPcode指定
    "action": "remove" or "invalidate"# 削除 or 無効化
    "domain" : "production" or "staging"# 本番環境 or ステージング環境
    "objects" : [ <オブジェクトのリスト>]

    詳細については、以下のリンク先をご参照下さい。

  • Content Control Utility Resources
  • 6. Purgeリクエストの進捗を確認する

    キャッシュのPurgeのリクエストが完了するには、やや時間がかかります。そのため、リクエストの進捗を確認するAPIも準備されています。

    以下のような Purge ステータス確認リクエストを作成します。名前は check.py にしました。

    以前のスクリプトからの変更点は、Purge対象を指定するヘッダー情報のブロックが必要なくなるのと、緑字の部分です。

    import requests
    import json
    from akamai.edgegrid import EdgeGridAuth
    from urlparse import urljoin
    baseurl = 'https://akab-3mmaaxfjw6wptqbl-eybzetlx6h7n3lyd.purge.akamaiapis.net/'
    s = requests.Session()
    s.auth = EdgeGridAuth(
    client_token='akab-3brdiu2qy2arerered3u-w4c3dqnnqpzxcrts',
    client_secret='4qSmEiJbkM2fuwsxDTEDNUM8XYwY9QIH6t8IDZ3DE=',
    access_token='akab-szimdreaw243854xud5qxszfjr3'
    )

    progressuri = "/ccu/v2/purges/74087c05-a25f-11e6-b019-fbc47af7a6cd"#(※1)

    result = s.get(urljoin(baseurl,progressuri))
    print result.status_code
    print json.dumps(result.json(),indent=2)

    (※1)URIの最後に付いている値はPurgeリクエストを実行した時に返ってきた"purgeId"の値です。


    以下のように 200 が返ってくれば、リクエストは成功です。

    [ec2-user@ip-172-31-12 ~]$python check.py
    200
    {
    "originalEstimatedSeconds": 240,
    "purgeId": "74087c05-a25f-11e6-b019-fbc47af7a6cd",
    "originalQueueLength": 4,
    "supportId": "17SY1478245229193836-268903616",
    "httpStatus": 200,
    "completionTime": "2016-11-04T07:24:14Z",
    "submittedBy": "1-BGIGR/OPEN",
    "purgeStatus": "Done",
    "submissionTime": "2016-11-04T07:22:33Z"
    }
    [ec2-user@ip-172-31-12 ~]$

    上記の例では、"Done"が Purge のステータスとして返ってきていますが、Purge のステータスには以下のものがあります。

  • Done (完了)
  • In-Progress (処理中)
  • Unknown (不明)
  • 7. リクエストのQueue長の確認

    Purgeリクエストは、処理用のQUEUEに入れられた後、処理が行われます。QUEUEに溜まっているリクエスト数を表すQUEUEの長さもAPIを使って確認する事ができます。

    実は、はじめのセットアップ確認用に作成した test.pyは、リクエストQueueの長さ確認用のスクリプトと同じものです。 そのまま使っても良いのですが、ここでは、length.pyという名前にして、JSONの出力形式だけ少し綺麗に整えました(緑字の部分)。

    import requests
    import json
    from akamai.edgegrid import EdgeGridAuth
    from urlparse import urljoin
    baseurl = 'https://akab-3mmaaxfjw6wptqbl-eybzetlx6h7n3lyd.purge.akamaiapis.net/'
    s = requests.Session()
    s.auth = EdgeGridAuth(
    client_token='akab-3brdiu2qy2arerered3u-w4c3dqnnqpzxcrts',
    client_secret='4qSmEiJbkM2fuwsxDTEDNUM8XYwY9QIH6t8IDZ3DE=',
    access_token='akab-szimdreaw243854xud5qxszfjr3'
    )

    result = s.get(urljoin(baseurl,'/ccu/v2/queues/default'))
    print result.status_code
    print json.dumps(result.json(),indent=2)

    以下のように 200 が返ってくれば、リクエストは成功です。

    [ec2-user@ip-172-31-12 ~]$ python length.py
    200
    {
    "httpStatus": 200,
    "detail": "The queue may take a minute to reflect new or removed requests.",
    "queueLength": 0,
    "supportId": "17QY1478246638804549-226940096"
    }
    [ec2-user@ip-172-31-12 ~]$

    この例では、QUEUEの長さは0になっています。

    8. 最後に

    このドキュメントでは、CCU Version 2と呼ばれるAPIを使用しましたが、現在 "Fast Purge"と呼ばれるより高速にキャッシュのPurgeを行える新バージョン(version 3)のAPIもLA(Limited Availability)として使用可能になっています。"Fast Purge"では、約5秒前後でキャッシュの更新が可能になっています。

    詳細については以下のリンクをご参照下さい。

  • Moving to CCU V3, Now With Fast Purge! | Akamai Community
  • The CCU API
  • CCU API Use Cases

  • この記事作成時点では、まだ実装されていませんが、将来的にはキャッシュするコンテンツに"タグ"を付けて、共通の"タグ"が付いているファイルだけを同時にPurgeする機能も実装予定である事が言及されています。

    9.参考リンク

    文中で紹介したリンクを含みますが、もう一度、最後に開発の参考となるリンクをまとめておきます。

    Content Control Utility V2の基本情報
  • Content Control Utility

  • Akamaiが提供している各種言語のクライアント・ツール
  • Open Source API Clients

  • APIを使用するためのAuthorizationヘッダーに関する情報
  • API Client Authorization

  • デベロッパー・コミュニティのOPEN APIカテゴリ
  • {OPEN} Developer Community | Akamai Community



  • Leave a comment