DNAC: Postman による API アクセス

[mnagao]

• はじめに
• 事前準備
• Environment の作成
• Collection の作成
• 認証トークン取得定義
• 目的の API へのアクセス
• [廃止予定] Cookie を使う場合の設定
• 参考

 

はじめに

DNA Center に関するトラブルシューティングにおいて API アクセスの状況を確認することが必要な場合があります。このドキュメントでは Postman を用いて DNA Center の API へアクセスする場合の手順を説明します。

事前準備

DNA Center への HTTPS アクセスにて OS で検証可能でない証明書を使用している場合は、Settings で証明書の検証を無効にします。(デフォルトの自己署名証明書のまま使用している場合など)

Environment の作成

DNA Center への API アクセスでは X-Auth-Token ヘッダに認証トークンを設定してアクセスしますので、パラメータを保存するための Environment を作成します。
以下の例では他に DNA Center の管理 IP を cluster_ip として保存しています。

Collection の作成

DNA Center へのアクセス設定をひとまとめにしておくため、New Collections より Collection (フォルダ) を作成します。名前以外の設定は特に必要ありません。

認証トークン取得定義

https://$DNAC/api/system/v1/auth/token に Basic 認証を用いてアクセスして認証トークンを取得し、認証トークンを次回以降のアクセス時に X-Auth-Token ヘッダとして利用するための設定を行い、保存します。

• Environment として上記で作成した DNAC を選択します。
• 新規タブ選択します。
• POST を選択し、URLに http://{{cluster_ip}}/api/system/v1/auth/token を記入します。
• Authorization タブにて TYPE = Basic Auth を選択し、DNA Center GUI のユーザ名・パスワードを記入します。
• Preview Request をクリックします。

• Headers タブに遷移します。
• Preview Request をクリックすることでユーザ名・パスワードが Base64 エンコードされ、Authorization ヘッダが自動生成されていることが確認できます。
• Content-type として application/json を追加します。

• Tests タブに以下のスクリプトを記入し、api/system/v1/auth/token へのアクセスで得た認証トークンを Environment の X-Auth-Token に保存・再利用できるようにします。
  

  var jsonData = JSON.parse(responseBody);
  var auth_token = jsonData.Token;
  pm.environment.set("X-Auth-Token", auth_token);

• Save をクリックし、api/system/v1/auth/token へのアクセス設定を DNAC コレクションに保存します。

• Send をクリックすると DNA Center へのアクセスが行われ、認証トークンが取得されます。
• Environment quick look をクリックすると api/system/v1/auth/token  からのレスポンスと同じ値が Environment = DNAC に X-Auth-Token として追加されていることが確認できます。

目的の API へのアクセス

認証トークンを取得できたら、任意の API へのアクセスを設定します。ここでは api/v1/group へのアクセスを例として記載します。認証トークンの有効期限が切れてエラーになった場合は再再度 api/system/v1/auth/token へアクセスし、認証トークンを更新してください。

• Environment として定義済みの DNAC を選択します。
• 新規タブを選択します。
• アクセスする API で使用する HTTP メソッドを選択し、API の URL を記入します。
• Headers タブにて Content-type = application/json と X-Auth-Token == {{X-Auth-Token}} を定義します。{{parameter}} は選択された Environment から取得します。
• Send をクリックすると API アクセスが実行されレスポンスが表示されますので、必要に応じてコピーしてファイルに保存します。

•  必要に応じて作成したリクエストを Collection に保存すると、再利用できます

[廃止予定] Cookie を使う場合の設定

上記は api/system/v1/auth/token へ HTTP POST アクセスし、JSON形式で認証トークンを取得していますが、Cookie として認証トークンを取得する方法もあります。取得できる結果に差異はありませんが、この API は将来廃止される予定です。

• api/system/v1/auth/login に Basic 認証で HTTP GET すると、success というレスポンスを得られます (JSON データではないので Raw をクリックして確認します)

• その際、DNA Center から認証トークンが X-JWT-ACCESS-TOKEN 属性として Set-cookie されます。

• 取得した Cookie は他の API アクセス時に自動適用されますので、目的の API アクセスの際は Content-Type: application/json ヘッダを指定すればアクセスできます。

参考

各 API のアクセスに必要なパラメータは DNA Center の GUI (https://$DNAC/dna/apidoc) や DevNet のサイト でご確認ください。

[mnagao]

エディタとして VSCode をご使用の方は、拡張機能 REST Client を用いて Postman より簡単に API アクセスできます。DNAC: curl/wget による API アクセス のコメント欄をごらんください。