Akamai API入門 Part 1 — API Client & EdgeGrid
2010 年代以後、IT 技術と環境の飛躍的な発展が進む一方、世界的な少子化の影響もあり IT 業界に従事するエンジニア数は減少傾向にあります。その結果、情報資産管理自動化の必要性が増し、運用管理文化の改革を求める DevOps 概念の普及が推し進められました。そして DevOps や自動化を可能とする、異なる操作方法を持った機種間の汎用操作インターフェース技術として API が広く使われるようになりました。
Akamai も DevOps への全面的な参加を表明し、Akamai {Open} プロジェクトという名の下で様々な活動を進めており、より多くのユーザーに Akamai ソリューションを活用した自動化を提供し続けるミッションを遂行してきました。特に単なる API の提供に留まらず、初心者の方にも Akamai の API を利用した自動化を実現して頂けるよう、様々なツールやガイドを提供しています。
しかしながら、直接的に開発に縁がなかった方々にとって API や DevOps はまだ開発者の専有物と思われる場合も多く、API の利用を高い壁として感じてしまうこともあるようです。例えば、API を使うためには様々なプログラミング言語を深く学び、ツールにも慣れる必要があるに違いないと考え、なかなか気軽に手が出せていないのではないでしょうか。
本記事ではプログラミングとあまり縁がない方が初めて API を使うといった観点で、Akamai の API を探し、準備し、活用するまでの道のりを実例と共に説明します。特に、使いたい API の検索方法や、見つかった API を使っていくまでの流れを分かりやすく説明することに重点をおいています。
本記事は二つの Part で構成されており、最後まで進めて頂くことで、必要な API をユーザー自身で検索でき、使って頂けることを目指します。なお、API を利用した自動化に汎用性と柔軟性を持たせるため、開発者以外でも広く使われている Python を利用します。本記事で使ったすべての Source Code も例として提供します。(Part 2 の記事はこちら)
【Part 1 アジェンダ】
【Akamai の DevOps 紹介】
Akamai の DevOps 活動は多方面で多く存在し、日々その領域を広げています。それらの情報は下記二つのサイトに集約されています。
■https://developer.akamai.com ※以後、本記事では DEV サイトと表現します。
Akamai の DEV サイトでは主に下記情報を提供しています。
- Akamai {Open} プロジェクトの全体像、各種 DevOps アプローチの紹介、それらのガイド提供
- Akamai 製品に関する API 提供情報、API 利用ガイド提供
- 実技を加えた Blog 記事や Case Study など、DevOps における Akamai の活動内容全般の情報発信
なお、DEV サイト各ページの一番下にはサイトの表示言語を変更できる機能があります。例えば Japanese を選択することで DEV サイトのコンテンツが日本語で表示されます。
翻訳機能利用中には各ページの一番上に元の言語に戻るためのオプションが現れます。なお、翻訳されたテキストにマウスカーソルを移動すると翻訳前の原文を確認できます。
翻訳機能を利用すると DEV サイト全体のテキストが選択した言語で表示され、英語が苦手な方でも DEV サイトに馴染みやすい仕組みとなっています。ただ、本機能は機械翻訳に依存するため原文の意図と異なる誤訳になってしまう可能性があります。
加えて、表示テキストの変化により検索機能に影響することがあります。このような影響を防ぐため本記事は翻訳機能を使いません。必要に応じて翻訳機能をご利用いただければと思います。
■https://github.com/akamai ※以後、本記事では GIT サイトと表現します。
Akamai の GIT サイトでは、GitHub を利用して実際 DevOps に活用できる各種コードとスクリプトのサンプルを提供しています。これらは Akamai 社員が作成・管理していますが、Public GitHub なため誰でも意見を交わし、フィードバックすることができます。より積極的な DevOps を目指す方にぜひご活用頂きたいサイトです。
ここまで DEV と GIT の二つのサイトを紹介しました。両サイトの使い分けとしては、まず実現したいツールや API などの情報を DEV サイトで探し、具体的なコードの例やライブラリー、スクリプトが必要な場合は GIT サイトを訪問してみるといった流れです。本記事では両サイトから情報を取得する形で説明します。
【Akamai API 利用の第一歩】
本記事ではウェブセキュリティ製品でよく利用する Network list を API で操作してみます。DEV サイトのトップメニューで GET STARTED をクリックしてみましょう。左下にサブメニューが表示されます。私の目的は API なので API Authentication サブメニューに関連性高い情報があると想定できます。API Authentication をクリックします。
少し話が逸れますが、API 利用においてもセキュリティは非常に大事で、当然守られていますので普通は API のアクセス権限が必要となります。API 接近権限を持つというのは、コンフィグレーション変更と同等の操作権限を持つ意味であり、必要な人物のみ API を利用できるよう認証処理を行うのが一般的です。
DEV サイトの話に戻りますが、今見えているページでは API 認証手順を紹介しています。どうやら Akamai API を使うため API Client を Akamai Control Center で作成し、EdgeGrid を準備する必要があるようです。まずは単語だけ覚えておきましょう。
そして、同ページには関連性のある追加情報として EdgeGrid Code Examples と Browse Akamai APIs がありました。まず BROWSE APIs ボタンをクリックしてみます。
移動したページでは Akamai が提供する API 機能を種別単位で確認できます。
本ページはトップメニューからでも移動できます。DOCS - API Docs 順でクリックすると同じページに移動します。
検索バーにキーワードを入れることで関連性ある API のみ表示できます。私は Network Lists を API で操作したいので "network" と入力します。
結果、入力したキーワードが API 名又は説明に一致するものが表示されます。説明を読むと "Manage common sets of lists used by various Akamai security products and features" となっている Network Lists API v2 が探している API であることが分かります。API 名のリンクをクリックします。
該当 API の詳細情報を提供するページに移動しました。Overview を読むと私が求める API で間違いないと判断できます。では、具体的にどのような操作ができるかを確認します。
同ページの API Summary では、本 API カテゴリで操作可能な機能一覧を確認できます。Network List の確認、更新、追加、削除、適用まで運用に必要な機能が一通り揃っています。
ここまでの内容を整理します。
① API を利用の認証情報として API Client が必要
② API 認証情報を利用するときは EdgeGrid を使う
③ 'Network Lists' を API で操作するためには 'Network Lists API v2' を利用
Akamai の API を使うために必要な準備物の確認と、使いたい機能の API を検索する方法を確認しました。これより API Client と EdgeGrid について確認します。
【API Client 作成】
誰でも API アクセス・操作ができてしまうとセキュリティを守れないことはもちろん、設定変更によるサービスへの悪影響が発生する可能性もあります。よって各ユーザが使う API 権限を制御する必要があります。
Akamai API では API Client で API アクセス権限を制御します。これより API Client の作成方法を説明します。API Client 作成は ACC（=Akamai Control Center）で行います。
（※ACC のアカウントがない場合は Akamai 担当者にお問合せください。）
ACC メニューバーで「Identity & Access」を選択頂くか、検索バーに "identity" と入力後に現れる検索結果の中で「Identity & Access」を選択します。
Identity and Access Management メニューが表示されます。こちらは ACC のユーザ ID や API Client を制御するメニューです。自分用の API Client を作成するため、「New API client for me」ボタンをクリックします。
Create API client 画面に移動され、どのように API Client を作成するかを選択します。
Select API client type の中で３つのオプションがありますが、ここでは Myself を利用します。参考までに、Another user や Service account オプションは他人用や特定目的のための共通 API client を作成するための機能です。
「Quick」は自分が所属しているグループ内の全 API に対する権限を一気に付与する方法です。
「Advanced」は必要な API だけを選んで権限付与する方法です。
私は API 権限を制御したいので「Advanced」を選択します。
※グループとは？
Akamai は各種オブジェクト（配信設定等）を階層構造で管理しており、各階層のディレクトはグループと呼ばれます。ユーザ ID が上位階層に所属していると該当階層を含め配下全グループの制御権限を持ちます。
下記イメージで説明すると上位階層に所属しているユーザ A はトップレベルとその配下のグループ全体に対する権限を持ちます。ユーザ B とユーザ C は所属しているグループ又はその配下グループに対する権限を持ちます。
「Advanced」を選択した結果、Advanced 設定画面に移動します。
新規 API Client に対する情報登録や権限制御を行う画面となり、下記情報を登録していきます。
- Name：API Client 名を記載します。
- Description：API Client を表す補足情報（テキスト）を残します。
- Notification list：API Client の Credential 情報は 2 年間有効で、満了すると使えなくなるため更新が必要です。Notification list として email アドレスを登録しておくと Credential 満了が近づいたときにメールで通知します。
- APIs：Select APIs を選択することで制御必要な API 機能に限定して API アクセス権限を付与可能です。デフォルト（ALL APIs）では全 API アクセス権が付与されます。
- Groups：Restrict groups を選択することで制御必要な Group（もしくは Sub Group）のみ API アクセス権限を付与可能です。デフォルト（Same groups as {user id name}）では所属している Group を含め、配下の全 Group へのアクセス権が付与されます。
- Purge selections：API を利用した Purge 操作の権限を制御できます。Purge API を有効にするためには APIs で ALL APIs を選択するか、Select APIs で CCU（Content Control Utility）権限を付与する必要があります。
Name、Description、Notification list を記入した後 Select APIs を選択して API 権限を制御します。Select APIs を選択すると下記のポップアップが表示され、最初は全 API アクセス権限が有効になっています。まずは「Clear API selection」ボタンをクリックし権限を初期化します。
API 権限初期化後、権限を付与したい API を選びます。検索バーで使う機能のキーワードを入力すると API 名や Description が一致する API が表示されます。ここでは Network Lists の API に READ-WRITE 権限を付与したいため、"network" と入力した検索結果を確認しています。
必要な API の Access level 設定完了後「Submit」ボタンをクリックし変更内容を適用します。補足情報として、API 名前をクリックすると該当 API ドキュメントページ（DEV サイト）に移動できます。API の情報を確認できるので、API 権限付与のミスを防止できます。
Advanced 設定画面に戻り、今度は Groups 権限設定を確認します。Restrict groups を選択すると下記ポップアップが表示されます。
最初はユーザ I Dが所属する Group を含め、配下の全 Group の権限が付与されています。必要に応じて制御したい Group を選択しましょう。
Group 権限を制御する方法は API 制御と同じで、まず「Block all groups」ボタンをクリックし権限を初期化した後、権限を付与したい Group 名を検索バーで入力し該当 Group にチェックを入れます。本記事では Group 権限制御に変更はせずデフォルト設定を使います。
下記イメージは「Block all groups」ボタンをクリックした状態で、"shki" というキーワードで検索をかけている画面です。
Group 制御設定完了後、「Submit」ボタンをクリックし設定を適用、Advanced 設定画面に戻ります。設定内容を確認し問題なければ「Create API client」ボタンをクリックします。
これで API Client を作成できました。同時に本 API Client を利用した API 操作に必要な Credential 情報も生成されました。Credential 情報は API 操作時に必ず必要なものです。
特に、client_secret 情報は Credential が生成された一瞬でしか表示されないので、紛失しないように「Download」や「Copy credential」ボタンをクリックして Credential 情報のバックアップを取っておくことを推奨します。
client_secret 情報を忘れてしまうと探す方法はなく、同ページの Create credential をクリックし新しい Credential を作成する必要があります。
本ページでの作業は完了しましたので、一旦 ACC のページから離れます。
【EdgeGrid の準備】
API Client を作成し、API アクセスに必要な Credential 情報を取得しました。この Credential 情報はどのように使えばいいのでしょう。本来は Akamai API で定義されているスキームに沿って Credential 情報を利用したやり取りをもって認証処理行い、問題がなければ API を利用できます。しかしこれらの過程は API 利用者にとっては不便なもので、API 利用のハードルを上げてしまいます。
この不便さを改善するため、Akamai は API Client の Credential 情報を利用した認証スキームを処理するライブラリーを用意し、各種プログラミング言語やツールで利用できるよう配布しています。それが EdgeGrid です。
GIT サイト（https://github.com/akamai）で "edgegrid" と検索することで様々な環境に対応した情報が現れます。本記事で利用する Python におきましては EdgeGrid を PyPI にサードパーティライブラリーとして登録しているので PIP を利用した簡単な設置も可能です。
本記事では非開発者にも広く普及している Python を利用して EdgeGrid を使う準備を行います。Linux はどれを選択頂いてもいいですが、Python のバージョンは 2.7 ではなく 3.x 以上を使ってください。Python 2.7 は正式なサポートが終了していて、Akamai が提供する DevOps 関連ツールや API でも一部利用できないものがあります。私は Centos Linux 7 と Python 3.7.9 を使いました。
まず EdgeGrid ライブラリーを設置します。二つの設置方法があり、PIP を利用する方法とソースコードを利用する方法があります。これらの情報は GIT サイト（https://github.com/akamai/AkamaiOPEN-edgegrid-python）でも確認可能です。
本記事では PIP コマンドを利用します。下記はコマンド実行結果です。
[elfin@localhost ~]# pip install edgegrid-python
Collecting edgegrid-python
Using cached edgegrid-python-1.1.1.tar.gz (11 kB)
Requirement already satisfied: requests>=2.3.0 in /usr/local/lib/python3.7/site-packages (from edgegrid-python) (2.24.0)
Requirement already satisfied: pyOpenSSL>=0.13 in /usr/local/lib/python3.7/site-packages (from edgegrid-python) (19.1.0)
Requirement already satisfied: ndg-httpsclient in /usr/local/lib/python3.7/site-packages (from edgegrid-python) (0.5.1)
Requirement already satisfied: pyasn1 in /usr/local/lib/python3.7/site-packages (from edgegrid-python) (0.4.8)
Requirement already satisfied: urllib3 in /usr/local/lib/python3.7/site-packages (from edgegrid-python) (1.25.10)
Requirement already satisfied: chardet<4,>=3.0.2 in /usr/local/lib/python3.7/site-packages (from requests>=2.3.0->edgegrid-python) (3.0.4)
Requirement already satisfied: certifi>=2017.4.17 in /usr/local/lib/python3.7/site-packages (from requests>=2.3.0->edgegrid-python) (2020.6.20)
Requirement already satisfied: idna<3,>=2.5 in /usr/local/lib/python3.7/site-packages (from requests>=2.3.0->edgegrid-python) (2.10)
Requirement already satisfied: cryptography>=2.8 in /usr/local/lib/python3.7/site-packages (from pyOpenSSL>=0.13->edgegrid-python) (3.1)
Requirement already satisfied: six>=1.5.2 in /usr/local/lib/python3.7/site-packages (from pyOpenSSL>=0.13->edgegrid-python) (1.15.0)
Requirement already satisfied: cffi!=1.11.3,>=1.8 in /usr/local/lib/python3.7/site-packages (from cryptography>=2.8->pyOpenSSL>=0.13->edgegrid-python) (1.14.2)
Requirement already satisfied: pycparser in /usr/local/lib/python3.7/site-packages (from cffi!=1.11.3,>=1.8->cryptography>=2.8->pyOpenSSL>=0.13->edgegrid-python) (2.20)
Using legacy 'setup.py install' for edgegrid-python, since package 'wheel' is not installed.
Installing collected packages: edgegrid-python
Running setup.py install for edgegrid-python ... done
Successfully installed edgegrid-python-1.1.1
これで EdgeGrid 設置が完了しました。後は API Client の認証情報（Credential）を EdgeGrid ライブラリーで使えるようにする必要があります。二つの方法があります。
・Python コードファイル（.py）に直接 Credential 情報を書き込む方法（いわゆる Inline やハードコード方式）
・Credential 情報ファイルを別途用意し、その中身を読み込む方法（Linux ユーザの Home Directory に {.edgerd} ファイルを作成）
どの方法も動作結果の差はなく、どの方法を利用するかは自分が使う環境や好みに合わせて選択して頂きますが、本記事では {.edgerc} ファイルに Credential 情報を登録して使う方法を利用します。補足情報として、{.edgerc} ファイルで Credential 情報を登録しておくと Python 以外のプログラミング言語やツールでも EdgeGrid ライブラリーを経由して API を使えます。
{.edgerc} ファイルを利用し EdgeGrid を実行するための Python コードを準備します。一からコードを作るのは大変なので、GIT サイトコード例を引用します。GIT サイトコード例に「>>>」の後ろにある文字列が Python 命令文ですので、この命令文を抜粋して edgegrid-example.py というファイルを作ります。
ここで一つ注意点として、GIT サイトの例にある urlparse ライブラリーは Python 2.7 でしか使えず、Python 3.x では urllib.parse に名前が変わりました。下記はこれらの内容を反映した Python コードファイルの作成例です。
[elfin@localhost ~]# cat> edgegrid-example.py
import requests
from akamai.edgegrid import EdgeGridAuth, EdgeRc
from urllib.parse import urljoin
edgerc = EdgeRc('~/.edgerc')
section = 'default'
baseurl = 'https://%s' % edgerc.get(section, 'host')
s = requests.Session()
s.auth = EdgeGridAuth.from_edgerc(edgerc, section)
result = s.get(urljoin(baseurl, '/diagnostic-tools/v2/ghost-locations/available'))
result.status_code
result.json()['locations'][0]['value']
(Ctrl+Dで入力終了)
そして、自分の Home Directory に {.edgerc} ファイルを作成し、バックアップしておいた API Client の Credential 情報を貼り付きます。Credential 情報を貼り付けるときに、その Credential の識別子 (Section Name) を決めてかっこ（[ ]）で囲みます。
ここでは識別子を [jp-blog] と命名しました。
[elfin@localhost ~]# cd ~
[elfin@localhost ~]# pwd
/home/elfin
[elfin@localhost ~]# cat> .edgerc
[jp-blog]
client_secret = 85OUDZLhmN3qRF9Xpg2ANTogVXbgKEBSRnj4S/7SwVE=
host = akab-h4sy2jdnd3ewvknx-6dqkikuck3x35dzx.luna.akamaiapis.net
access_token = akab-q4zrncp3ymvb6jbb-du5to3mwasvwp6yp
client_token = akab-5hvnngfcvucz2pcz-upn4xcuepvhpulcc
(Ctrl+Dで入力終了)
上記 Credential 情報は皆様のスムーズな理解のため元の Credential 情報をそのまま記入していますが、本記事の公開時点では破棄しているので、使えません。皆様は各自が生成、取得できた Credential 情報を使って {.edgerc} ファイルを作成ください。
これで EdgeGrid ライブラリーを使うための準備が完了しました。では次の記事で実際 API を使ってみます。(Part 2)
