はじめに
https://supportforums.cisco.com/t5/-/-/ta-p/3372688 では Postman による API アクセスを紹介しましたが、トラブルシューティング時に Postman が使えない場合や、CLI の方が効率的だがスクリプトを組む程でもない場合向けに curl および wget での API アクセス例を紹介します。
下記は macOS (bash version 3.2.57(1)) 上での curl 7.54.0 および wget 1.19.5 (Homebrew よりインストール) を使用した例ですが、必要なオプションや特殊文字のエスケープの必要性の有無などは要件/環境に依存する可能性があります。“ ” と " の違いなどにもご注意ください。
なお、検証環境などで DNAC で自己署名証明書や検証不可能な電子証明書を使用している場合は curl -k または wget --no-check-certificate を指定する必要があります。
基本的な流れは、以下です。
- HTTP Basic 認証を用いて GET api/system/v1/token し、JSON 形式で認証トークンを取得
- 認証トークンを X-Auto-Token の値として任意の API へアクセス
POST/DELETE など DNAC のデータベース変更を伴う操作を行う場合は十分にご注意ください。
curl
$ export JSON="Content-Type: application/json" $ echo $JSON $ curl -k -u admin:CiscoDNA! -H "$JSON" -X POST https://10.70.70.231/api/system/v1/auth/token $ export DNACAUTH="X-Auth-Token:<取得した認証トークン>" $ echo $DNACAUTH $ curl -k -H "$DNACAUTH" -H "$JSON" -X GET https://10.70.70.231/api/v1/group
-----
$ export DNACAUTH=$(curl -k -H "Content-Type: application/json" -u admin:CiscoDNA! -X POST https://10.70.70.231/api/system/v1/auth/token | jq -r .Token)
または
$ DNACAUTH=$(curl -u admin:CiscoDNA! -k -H "Content-Type: application/json" -X POST "https://10.70.70.231/api/system/v1/auth/token" | awk -F ":" '{print $2}' | awk -F "\"" '{print $2}')
のようにすれば上記の Token (JWT) 取得を1行で済ませ、以下のように API アクセスすることもできます。
$ curl -k -H "X-Auth-Token:$DNACAUTH" -H "Content-Type: application/json" -X GET https://10.70.70.231/api/v1/group
wget
$ export JSON="Content-Type: application/json" $ echo $JSON $ wget --auth-no-challenge --no-check-certificate --method=POST --http-user=admin --http-password=CiscoDNA! https://10.70.70.231/api/system/v1/auth/token -O - -q $ export DNACAUTH="X-Auth-Token:<取得した認証トークン>" $ wget --no-check-certificate --header="$JSON" --header="$DNACAUTH" https://10.70.70.231/api/v1/group -O -
DNACは HTTP 認証プロトコルのネゴシエーションは行いませんので、直接 HTTP Basic 認証を行うために --auth-no-challenge を指定します。
不要なファイルをダウンロードしないよう、出力先は -O - で stdout にしていますが、必要に応じてファイル出力にしてください。
[廃止予定] Cookie 認証を使う例
api/system/v1/auth/login にアクセスし、Cookie として認証トークン (X-JWT-ACCESS-TOKEN 属性) を取得する手法もありますが、将来廃止予定です。
Cookie を使う場合、curl/wget とも Domain 属性が syntax error となるため curl の -c/-b オプション、wget の --save-cookie/--load-cookie オプションが使用できません (DNAC 1.2.1 の時点) ので、環境変数に認証トークンを一時的に登録する例を記載します。
curl
$ export JSON="Content-Type: application/json" $ echo $JSON $ curl -k --dump-header - https://admin:CiscoDNA\!@10.70.70.231/api/system/v1/auth/login $ export DNACAUTH="X-JWT-ACCESS-TOKEN=<取得した認証トークン>" $ echo $DNACAUTH $ curl -k --cookie $DNACAUTH -H "$JSON" -X GET https://10.70.70.231/api/v1/group
注: レスポンスヘッダの Cookie を確認するため、--dump-header オプションを使用し、username/passwordは URL内にエンコードしています。
wget
$ export JSON="Content-Type: application/json" $ echo $JSON $ wget --auth-no-challenge --no-check-certificate --http-user=admin --http-password=CiscoDNA! https://10.70.70.231/api/system/v1/auth/login --server-response -q O - $ export DNACAUTH="Cookie: X-JWT-ACCESS-TOKEN=<取得した認証トークン>" $ echo $DNACAUTH $ wget --no-check-certificate --header="$JSON" --header="$DNACAUTH" https://10.70.70.231/api/v1/group -O -
レスポンスヘッダの Cookie を確認するため、--server-response を指定します。
DNAC は HTTP 認証プロトコルのネゴシエーションは行いませんので、直接 HTTP Basic 認証を行うために --auth-no-challenge を指定します。
不要なファイルをダウンロードしないよう、出力先は -O - で stdout にしていますが、必要に応じてファイル出力にしてください。
参考
各 API のアクセスに必要なパラメータは DNA Center の GUI 上で Swagger ページ (API Tester https://$DNAC/dna/apitester バージョン 1.x のみ) や DevNet のサイト でご確認ください。
トークンは JWT (JSON Web Token, RFC7519) です。署名アルゴリズムは RS256, 有効期限は 1 時間です。
$ curl -k -H "Content-Type: application/json" -u admin:CiscoDNA! -X POST https://10.70.70.231/api/system/v1/auth/token | jq -r .Token % Total % Received % Xferd Average Speed Time Time Time Current Dload Upload Total Spent Left Speed 100 727 100 727 0 0 3147 0 --:--:-- --:--:-- --:--:-- 3147 eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiI1Y2I4NTk1MjE3OTA3NDAwNGM1OGE1MDYiLCJhdXRoU291cmNlIjoiaW50ZXJuYWwiLCJ0ZW5hbnROYW1lIjoiVE5UMCIsInJvbGVzIjpbIjVjYjg1OTUxMTc5MDc0MDA0YzU4YTUwNSJdLCJ0ZW5hbnRJZCI6IjVjYjg1OTUwMTc5MDc0MDA0YzU4YTUwMyIsImV4cCI6MTU5NTczMDY0MSwiaWF0IjoxNTk1NzI3MDQxLCJqdGkiOiJhNmVjM2IwZC1lN2Y5LTRjNDItYjMzZC1lOGZiNGUwYjY3OGYiLCJ1c2VybmFtZSI6ImFkbWluIn0.uoB4fByrxNn7eivPaVsBd3yoPrAsf7BIkKfU8WJF44sK8qONDMqFbvaVB9qq1FU7kzPxD3lz47BJDluClghfJoqG8YFHujO0ND_Zt1OZ7nCTc4ipLTz4batBdRkweGM4ZJlJfvfSJxjMtPro5sfbS0ic0L3ajuhYBuEFQhzn24wOLkSG4OsNMCA-MalfWMPZiMAWIri0heci_uSMpD7HQrfzYt2j70SRFZMt8fAMZFPFxUAs2uwweoY0_v0p0IR7VH3no3VPjq7RzNkVPrbWKhURThHe0uxNrP6biUIa5dxCx0Fm0G4jVYfXh9BTf7YGWqAm0fg9BTA4rIXcvPkk1w $ echo eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiJ9 | openssl enc -d -base64 {"typ":"JWT","alg":"RS256"} $ echo eyJzdWIiOiI1Y2I4NTk1MjE3OTA3NDAwNGM1OGE1MDYiLCJhdXRoU291cmNlIjoiaW50ZXJuYWwiLCJ0ZW5hbnROYW1lIjoiVE5UMCIsInJvbGVzIjpbIjVjYjg1OTUxMTc5MDc0MDA0YzU4YTUwNSJdLCJ0ZW5hbnRJZCI6IjVjYjg1OTUwMTc5MDc0MDA0YzU4YTUwMyIsImV4cCI6MTU5NTczMjE5MiwiaWF0IjoxNTk1NzI4NTkyLCJqdGkiOiI1Y2QwM2M2MS0wNTI3LTRiMDItOTRiYi04OTJlNWUzMjQ2NzEiLCJ1c2VybmFtZSI6ImFkbWluIn00 | openssl enc -d -base64 {"sub":"5cb85952179074004c58a506","authSource":"internal","tenantName":"TNT0","roles":["5cb85951179074004c58a505"],"tenantId":"5cb85950179074004c58a503","exp":1595732192,"iat":1595728592,"jti":"5cd03c61-0527-4b02-94bb-892e5e324671","username":"admin"}
有効期限: exp - iat = 1595732192 - 1595728592 = 3600 秒 base64 デコードには padding が必要になる場合があります。
エディタとして VSCode をご使用の方は、拡張機能 REST Client を用いてより簡単に API アクセスできます。テキストファイルの拡張子を .http とすれば下図のように "Send Request" のリンクが挿入され、コマンドパレットからのコマンド呼び出し不要で API アクセスが行えます。このツールでは電子証明書の検証は行わないようです。
まず最初に、DNA Center の IP, Credential といった基本的な変数を定義します。
次に認証トークン取得 API (POST api/system/v1/auth/token) を "login" という名前で定義し、レスポンスで得た JSON にある Token を "@token" に代入するよう定義しておきます。
これで、一度 login の "Send Request" をクリックすれば、取得した token を他の API コールで利用できるようになります。
あとは使用したい API を以下のようなフォーマットで記述します。"###" を書いていれば "Send Request" が自動的に挿入されます。
###
[Method] [URL]
[Header-Type] [Value]
[JSON データ(POST等の場合)]
テキストファイルですので、 IP, Credential のほか、下図のオフセット (?offset=1&limit=100) など様々なものが手軽に変更できます。
