Python での APIC-EM API：基礎 – Cisco DevNet の開発者サポート

概要
API-EM API call についての基本的な事項
API-EM API call を生成する Python のカスタムスクリプトを書く方法について

前提条件
REST API と JASON にある程度の見識があること

APIC-EM コントローラ向けの API call を生成します。初期設定では、これらのラボはhttps://sandboxapicem.cisco.com/で Cisco DevNet Sandbox の APIC-EM を使っています。

PC のセットアップ

ご自身の PC をセットアップするために、下記の手順を行ってください。
( シスコが配布したハードウェアをお使いの場合、もしくはこれらのアイテムをすでにセットアップ済の場合、次のセクションに進んでください。 )

Git のインストール

https://git-scm.com/downloads から Git をインストールしてください。

Python 3.x のインストール

https://www.python.org/downloads/ から Python 3.x のダウンロードとインストールを行って下さい。

Request ライブラリのインストール

リクエストのダウンロードとインストール：ご自身の適切なオペレーティングシステム向けの Humans 向けの HTTP

このライブラリをインストールすると、ご自身の Python スクリプト内で REST call を生成することができるようになります。

mac OS 向けには、下記のコマンドを使って下さい。
sudo curl -O https://raw.githubusercontent.com/pypa/pip/master/contrib/get-pip.py
sudo python3 get-pip.py
pip3 install requests

Windows 端末では、下記の手順に従ってください。

Windows 端末では、pip パッケージが Python3.4 についてきます。入力して Pip パッケージがご自身の Python3 にあるか確認してください。
bash
C:\>pip –V
pip 1.5.6 from C:\Python34\lib\site-packages

もし pip が Python34 にあれば、下記を入力してください。
bash
pip install requests

APIC-EM Git repo のクローンと確認

シスコイベントで、シスコが配布したハードウェアをお使いの場合、下記のタスクが既に完了しているはずです。

ラボのサンプルコードが C:\apicem-apis-with-python-sample-codes\basic-labs にダウンロードされています。

apicem_config.py ファイル内にある APICEM_IP パラメータがトレーニングで利用可能な API_EM コントローラを使うよう設定されています。

もし、その場合、次のステップに進めます。

作業用ディレクトリを作成してください。例えば：
mkdir \workingdir\

作業用ディレクトリに APIC-EM サンプルコードをクローンしてください。例：
cd \workingdir\
git clone https://github.com/CiscoDevNet/apicem-apis-with-python-sample-codes

git clone が完了したら、下記のラボ内で使われている Python ファイルを取得します。

初期設定では、下記に示すようにこれらのファイルは sandbox のシスコ APIC-EM に向けて送る API call を設定されています。
APICEM_IP = "sandboxapicem.cisco.com"

異なるコントローラを使うため、apicem_config.py の設定ファイルを設定します。
例えば、： username/workingdir/apicem-apis-with-python-sample-codes/basic-labs/apicem_config.py
apicem_config.py ファイルを編集し、APICEM_IP 変数で使う APIC-EM コントローラの URL か IP アドレスを割り当てます。

もしコントローラが特定のポート番号上でリッスンするように設定されている場合、URL や IP アドレス内のポート番号の値を含んでいます。

ステップ１： APIC-EM REST API の基礎を学ぶ

概要

APIC-EM コントローラは、エンターブライズ、WAN、とキャンパスネットワークにノースバウンド REST API に公開しています。ネットワークエンジニアとアプリケーションはコントローラと相互作用するようにこの REST API を使っています。コントローラのネットワークプログラマビリティとネットワークコントロールヘルプ IT オーガ内ゼーションは条件の変更に対して、対応しています。 APIC-EM コントローラは、ネットワークコントロールプレーンへのサウスバウンドインターフェースを持っています。それは、他のネットワークデバイスと相互作用し、管理するためにこれらのインターフェースを使用しています。

そのため、コントローラを管理し、ご自身のアプリケーションに dynamic software-defien networking ( SDN ) 機能を追加するために REST API を使うことができます。

スクリプトの実行

このラボ内でスクリプトを実行するために、mac OS 内もしくは Linux ターミナル内で、python3 scriptname と入力してください。Windows のコマンドプロンプト内で、py -3 scriptName もしくは、python scriptName と入力してください。あるいは、Python IDE, IDLE を使うことができます。mac OS ターミナル内で、Python3 向けの IDLE を実行するために idle3 と入力してください。 Windows では、IDLE を実行するために開始メニューを使ってください。

APIC-EM REST API URL

Cisco APIC-EM コントローラ上の API エンドポイントの URL は下記のパーツがあります。
https://fqdn-Or-IPofController/api/v1/api_itself

Where:
https://fqdn-Or-IPofController は、base URL です。もし必要な場合は、URL はポート番号を含むことができます。

api/vi/ は NB REST API のバージョン番号です。
/api_itself は API エンドポイントです。
Python から HTTP リクエストを発行します。
API-EM REST API は、作成、読み取り、更新そして削除の下記のスタンダード HTTP "CRUD" メソッドを使用しています。

POST はデータを生成します。
GET はデータを読み取り（取得）します。
PUT は、データを更新します。
DELETE は、データを削除します。

注意事項：安全のために、APIC-EM API は、常に POST、PUT リクエストパラメータと引数をリクエストペイロード内でJSON 形式にフォーマットされたペアのキー値としてフォーマットしています。

下記の一部コードサンプルは、これらのそれぞれの HTTP リクエストを発行する python request ライブラリを利用する方法を表しています。

GET
データを取得するために、Pytyon スクリプトは下記のような GET リクエストを発行しています。
import requests
url = "https://fqdn-Or-IPofController/api/v1/api_itself"
response = requests.get(url,verify=False)
# verify=False means not verifying the SSL certificate

POST
データを生成するために、Python スクリプトは下記のような POST リクエストを発行しています。
import requests
import json

json_obj = {
"key":"value"
}
url = "https://fqdn-Or-IPofController/api/v1/api_itself"
# need to specify content type -json- for POST request #
headers = {'content-type': 'application/json'}
response = requests.post(url, json.dumps(json_obj), headers=headers,verify=False)

PUT
データを修正するために、Python スクリプトは下記のような PUT リクエストを発行します。
import requests
import json

json_obj = {
"key":"value_to_change"
}
url = "https://fqdn-Or-IPofController/api/v1/api_itself"
# need to specify content type -json- for PUT request #
headers = {'content-type': 'application/json'}
response = requests.put(url, json.dumps(json_obj), headers=headers,verify=False)

DELETE
データを削除するために、Python リクエストは下記のような DELETE リクエストを発行します。
import requests
url = "https://fqdn-Or-IPofController/api/v1/api_itself"
response = requests.delete(url,verify=False)

APIC-EM REST API リファレンス

API のより詳細な情報は、下記のリンクを確認してください。

Cisco APIC-EM API リファレンスドキュメント

次のステップ

下記のラボは、Cisco APIC-EM コントローラ API と相互作用する簡単な Python アプリケーションを生成します。

APIC-EM コントローラからライブレスポンスを確認するために各ラボセッション内でスクリプトを実行してください。

ステップ２：新しいサービスチケットを生成し、全ての APIC-EM ユーザの情報を取得してください。

ステップ３：ネットワークデバイス関連の API を使ってください。

ステップ４：新しいサービスチケットを作成して使用してください。

目的

RBAC とサービスチケットの導入

RBAC とは何か、またサービスチケットが必要な理由

Cisco APIC-EM 上の Role-Based Access Control ( RABC ) は各ユーザアカウントにセキュリティロールを割り当てます。そのロールは、そのユーザアカウントに対して、どの Cisco APIC-EM リソースとオペレーションが利用可能か決定します。その Cisco APIC-EM コントローラは、下記のロールと特権を定義づけます。

Administrator ( ROLE_ADMIN ) は、ユーザとアカウントの追加と削除ができる機能を含む全ての Cisco APIC-EMリソースに対する完全な管理者特権をユーザに与えます。

Policy Administrator ( ROLE_POLICY_ADMIN ) はユーザにポリシーの作成と管理を可能にします。

Observer ( ROLE_OBSERVER ) は、Cisco APIC-EM に対してプライマリ読み取り専用特権をユーザに与えます。

Installer ( ROLE_INSTALLER ) は、デバイスのデプロイをして、デバイスのステータスを確認するために、ユーザがリモートで APIC-EM コントローラにアクセスするために Cisco Plug と Play Mobile App を使えるようにします。

インストーラは、Cisco APIC-EM GUI に直接アクセスすることはできません。

セキュリティトークンは、一つの値として、ロールインフォメーションとユーザアイデンティティをカプセル化するサービスチケットとして知られています。

RBAC-governed API は、アクセスコントロール決定を行うためのサービスチケットを使います。それゆえ、開始するためには、ご自身のユーザネームとパスワードと一緒に Cisco APIC-EM に POST／ticket リクエストを送ります。もし、APIC-EM コントローラがご自身のリクエストを承認する場合、承認済のユーザアカウントで関連する role をカプセル化するサービスチケットを返します。

サービスチケットを取得したら、ご自身がコントローラに送る後続の call の全てにそのサービスチケットを含みます。

コントローラがそれらの call を取得する際に、call によって要求されたアクションを起こす前にそのサービスチケットを確認します。

サービスチケットの生成

そのため、サービスチケットの取得のために

１．ご自身が以前に同期したファイル間で lab1-1-post-ticket.py スクリプトを配置してください。例：

apicem-apis-with-python-sample-codes\basic-labs\lab1-1-post-ticket.py

２．もしご自身が初期のものに代わり、代わりの APIC-EM を使う場合、username と password パラメータの値を編集し、

編集したドキュメントを保存してください。正しい行にコメントアウトしていることを確認してください。

Mac でのコードを編集するために、テキストファイルを開くためのファインダーを使うか、ターミナルからファイル名で下記の open コマンドを使ってください。

PC でコードを編集するためには、テキストファイルを開けるためにエクスプローラを使うか、CLI からファイル名で下記のnotepad コマンドを使用してください。

３．スクリプトを実行するために、Python コマンドを使って下さい。例：

Linux か mac OS の場合： python3 lab1-1-post-ticket.py

Windows の場合： py -3 lab1-1-post-ticket.py or python lab1-1-post-ticket.py

コードリスティング： lab1-1-post-ticket.py

コメント付きのスクリプトコードがこちらです。

コードリスティング： lab1-1-post-ticket.py

lab1-1-post-ticket.py -クリックして開いてください。

出力されるスクリプトはこちらです。
('Request Status: ', 200)
('\nRaw response from POST ticket request:\n', u'{"response":{"serviceTicket":"ST-16302-cKDpKVcv0fek6nx5YeaT-
cas","idleTimeout":1800,"sessionTimeout":21600},"version":"1.0"}')
('\nPretty print response:\n', '{\n "version": "1.0", \n "response": {\n "idleTimeout": 1800, \n
"sessionTimeout": 21600, \n "serviceTicket": "ST-16302-cKDpKVcv0fek6nx5YeaT-cas"\n }\n}')
The service ticket you need is the value of serviceTicket attribute. For example:
"serviceTicket": "ST-16302-cKDpKVcv0fek6nx5YeaT-cas"

response_json = resp.json()
print ("ticket: ",response_json["response"]["serviceTicket"])

先述のコードからの出力はこちらのものと同様です。

ticket: ST-16302-cKDpKVcv0fek6nx5YeaT-cas

ファイル内にサービスチケットと他の再利用可能なアイテムを置く

ご自身のスクリプトの多くが、host url や username と password ようなサービスチケットと他の値を再利用してます。

これらのスクリプトはさらにリクエストや json などのような同じモジュールをインポートしています。

それゆえに、apicem.py ファイルの1か所で全てのアイテムを設定／定義／インポートすることは理にかなっています。

なぜならば、ご自身のスクリプトは、しばしば新しいサービスチケットを生成し、apicem.py ファイルにThisget_X_auth_token() 機能を追加しているはずです。

apicem.py ファイル内のアイテムにアクセスするには、下記のインポートステートメントでこのラボ内で各スクリプトを開始してください。
from apicem import *

このインポートステートメントで、ご自身が apicem.py 内の全てのリソースにアクセスできるようになります。

コードリスティング： apicem.py ファイル

apicem.py - クリックして開いて下さい。

サービスチケットの利用

ご自身が APIC-EM REST に送ったほとんどすべての API call は、サービスチケットを提供しているはずです。：そのリクエストが POST であるか、GET や PUT、DELETE であるかは問いません。

ご自身の call でサービスチケットを提供するには、X-Auth-Tolenheader を使って下さい。

ヘッダーはご自身のサービスチケットの値を含む name-value ペアです。：

{"X-Auth-Token": "service_ticket_value" }

service_ticket_value には、ご自身のサービスチケットの値を当てはめてください。リクエストを作成する度に、新しいサービスチケットを取得する必要はありません。しかしながら、サービスチケットの値は、有効で期限内のものでなければなりません。このラボ内では、単純化のため API 向けの call を作成する度に新しいサービスチケットを取得することで開始します。後ほど、サービスチケットの取得と再利用の方法を確認します。

下記の GET/user リクエストは、サービスチケットの利用方法を示しています。このリクエストは、APIC-EM ユーザのリストを返します。返されたリストの内容は、caller のロールによって管理されています。もし、caller が管理者権限を持っている場合、レスポンスは、全てのユーザのリストを含んでいます。もし、caller がオブザーバーロールを持っている場合、レスポンスは、caller のユーザ情報だけを含んでいます。GET/user リクエストはアーギュメントを要求していません。X-Auth-Token ヘッダーをご自身の GET/user リクエストに追加してください。X-Auth-Token の値は、ご自身が前回 POST/ 返されたチケットに送ったサービスチケットです。

lab1-2-get-user.py - クリックして展開してください。

出力

コントローラからのレスポンス body は、devnetuser username が ROLE_POLICY_ADMIN セキュリティロールを所有していることを示しています。
Executing GET 'https://sandboxapicem.cisco.com/api/v1/user'
Get 'user' Status: 200
{
"response": [
{
"authorization": [
{
"role": "ROLE_POLICY_ADMIN",
"scope": "ALL"
}
],
"username": "devnetuser",
"authSource": "internal"
}
],
"version": "1.0"
}

User 'devnetuser', role is the POLICY_ADMIN.

下記のイメージは、どのコードの部分がどの出力をしているのか、を示してします。ご確認できるとおり、２つの for ループステートメントがコードに書かれています。

外側のループは、”response” 内の内容を反復しています。内側のループは、"authorization" 内の内容を反復しています。

ステップ３：ネットワークデバイス関連のAPIを使う

目的

ネットワークデバイス情報を取得するために下記のネットワークデーバイス関連の API をどのように使うか学ぶ

GET /network-device、 GET /network-device/{networkDeviceId}/config と GET /interface/network-device/{deviceId}

ネットワークデバイス情報を含むリストの作成方法とユーザにそのリストを表示する方法と

無効な値を拒否する一方でリスト内に現れる入力値をアクセプトするためにユーザと相互作用する方法を学ぶ

ネットワークデバイスとデバイスディスカバリの一意のネットワーク ID の割り当て

Cisco APIC-EM コントローラは各ネットワークデバイスに一意の ID を割り当てます。 IOS コンフィギュレーションとインターフェースのような特定のデバイスについての情報を取得するための様々なネットワークデバイス関連のcallのためのこの ID をパスすることができます。

注意事項： Cisco APIC-EM コントローラは、ネットワークに付随した物理デバイスをスキャンし、発見することができます。このディスカバリプロセスを初期化するために、コントローラ向けの POST/discovery call を送るか、その GUI 内にある Discovery アイコンをクリックすることができます。

Cisco DevNet Learning Labs 内にある Cisco APIC-EM コントローラは前回のディスカバリの結果が事前に設定されています。そのため、このラボでは、ディスカバリについては検討していません。

IOS 設定を表示するアプリケーション

このセクション内では、簡単なアプリケーションを作成し、デバイスを選択するようユーザに促します。ユーザが選択したデバイスの IOS コンフィギュレーションを表示します。

１．GET /network-device を使い、IP アドレスとともにネットワークデバイスのリストを表示します。

２．ユーザが選択したデバイスを許可します。

３．GET /network-device/{deviceId}/config を使い、特定のデバイスの IOS コンフィギュレーションを取得し、ユーザに IOS コンフィギュレーションを表示します。

タスク１： IP アドレスとともにネットワークデバイスのリストを与えます。

ユーザにネットワークデバイスのリストを表示するために、GET /network-device リクエストを発行することでネットワークデバイス情報を取得します。

レスポンスボディは、ネットワークデバイスのリストを返す。レスポンスの各ブロックは、１つの端末について、そのネットワークデバイス名、IP、タイプ、ネットワークデバイス ID や他の情報を提供します。

このネットワークデバイス ID は、GET /network-device/{deviceId}/config リクエストを含む多くのAPIに特定のネットワークデイバスを識別できるようにします。

GET /network-deviceレスポンスブロックは多くの属性を与えます。ご自身のアプリケーションは下記の属性を使っています。

instanceUuid や id は、ディスカバリの際に、ネットワークデバイスに割り当てられたコントローラの ID です。

hostname は、ネットワークデバイスの名前です。この属性は、ホストとデバイスを許可することに注意してください。

managementIpAddress は、ネットワークデバイスのIPアドレスです。

type は、スイッチやルータ、アクセスポイントのようなネットワークデバイスの種類です。

Code - GET /network-device、レスポンスを取得し、情報を表示します。

このサンプルコード内で、全ての認識されているデバイスの詳細情報を取得するために GET /network-deviceAPI をコントローラに向けて送ります。

そして、これらの値を含んだリストを作成するために役立つホスト名、managementIpAddress、種別、ID のレスポンスを取得します。

テーブルのリストを提供する python tabulate モジュールを使ってください。

簡潔にするために、tabulate.py ファイルは、先にご自身がクローンしたサンプルコードディレクトリ内に配置されています。

ソースコードファイルは、lab2-1-get-network-device-list.py です。

python ファイルを実行するために、下記のうちの１つを入力してください。

Linux もしくは mac OS:python3 lab2-1-get-network-device-list.py

Windows: py -3 lab2-1-get-network-device-list.py もしくは python lab2-1-get-network-device-list.py

コードリスト： lab2-1-get-network-device-list.py

lab2-1-get-network-device-list.py - クリックして展開してください。

下記のコードは、GET /network-divice からのレスポンスを取得する方法を示しています。

特定のデバイスのネットワークデバイス ID の取得方法とデバイスの IOS 設定を取得する方法を学びました。

このネットワークデバイス ID は、他の API でも同様に使用することができます。例えば、GET /interface/network-device/{id} request からのインターフェース情報を取得するこために使うこともできます。

デバイス ID からインターフェース情報を取得する

与えられたデバイス ID のインターフェースリストを取得するために、/interface/network-device/{id} をコールする機能を作成する必要があります。

より詳しい情報は、APIC-EM API リファレンスドキュメントを確認してください。

最新のコードリストのマイナーチェンジについては、IOS 設定やデバイスインターフェース情報の表示を行うかどうか、ユーザに選択させることができるようになっています。

１．新：ユーザに IOS 設定やインターフェース情報を表示するか確認します。：不正確な選択は拒否します。

２．ネットワークデバイスリストを作成します。このステップは、前回の例と同じです。

３．ユーザにリストからネットワークデバイスを選択するよう促します。

４．変更されました。：ステップ１と３内のユーザの選択を反映した API を呼び出します。
Code - GET '/network-device/{id}/config' and GET '/interface/network-device/{id}'

ソースコードファイル： lab2-3-get-network-device-id-config-interface.py

python ファイルを実行するために、下記のコマンドから１つを入力してください

Linux か macOS の場合： python3 lab2-3-get-network-device-id-config-interface.py

Windows の場合： py -3 lab2-3-get-network-device-id-config-interface.py もしくは、 python lab2-3-get-network-device-id-config-interface.py

コードリスト： lab2-3-get-network-device-id-config-interface.py

lab2-3-get-network-device-id-config-interface.py - Output をクリックして、展開してください。- クリックして展開してください。

この出力は、アプリとユーザ間の下記の相互作用の結果です。

インターフェースリストから ”１” を選択してください。

ネットワークデイバイスがアプリで一覧化されました。

ユーザが IP アドレスの 212.1.10.1 のネットワークデバイス７を選択しました。

アプリが IP アドレスが 212.1.10.1 のネットワークデバイス ID を取得し、"GET /interface/network-device/{id}" するネットワークデバイス ID を承認し、

インターフェースリストとレスポンスデータを表示しました。

セッションサマリ

このセッション内では、下記の事項について記述します。
ネットワークデイバイス情報を取得するための下記のネットワーク関連の API を使う方法
GET /network-device、GET /network-device/{networkDeviceId}/config と GET /interface/network-device/{deviceId}

ネットワークデバイス情報を含むリストの作成方法、ユーザにそのリストを表示する方法

そして、無効な値を拒否する一方でリスト内に表示された値の入力を承認するためにユーザとやりとりする方法

ネットワークデバイス ID は、多くの APIC-EM API へのキーです。ネットワークデバイス ID に関する API はさらに多くあります。マイナーチェンジでは、より多くの API 用に使われるこのアプリケーションを広めることができます。ここにいくつか例があります。

GET /network-device/{id}/location - 与えられたデバイス ID 向けのロケーションを取得する。

GET /network-device/{id} - 与えられたデバイス ID 向けのネットワークデバイスを取得する。

GET /license-info/network-device/{deviceId} - 与えられたデバイス ID でネットワークデバイス向けのライセンスのリストを取得する。

DELETE /network-device/{id}- インベントリから特定のネットワークデバイスを削除する。

このセクションの記事

関連記事