ステップ 1:APIC-EM API リソースの確認このラボでは REST API の例として APIC-EM API を使用します始める前に APIC-EM リソースを DevNet で確認しておく必要があります 1. ブラウザで DevNet にアクセスします Web ページの右上にある [

Size: px

Start display at page:

Download "ステップ 1:APIC-EM API リソースの確認このラボでは REST API の例として APIC-EM API を使用します始める前に APIC-EM リソースを DevNet で確認しておく必要があります 1. ブラウザで DevNet にアクセスします Web ページの右上にある ["

ひとおありはら
5 years ago
Views:

1 自分のコンピュータを設定する方法コーディング 101( 初級 1): REST API の基本このラボでは REST API の利用方法の基本と Pstman を使用して REST API のテストを行う方法について学びます目的所用時間 :20 分 REST API の使用方法の基本を理解する Pstman REST クライアントを使って API コールする方法について学ぶ前提条件このラボでは REST API コールを発信する Ggle Chrme ブラウザのアプリケーションである Pstman を使用します DevNet Zne のステーションにいる場合はすでに Pstman がインストールされています Ggle App Launcher から起動するか Chrme からここをクリックして Launch App を実行し起動させることができます APIC-EM コントローラへのアクセスこれらのサンプルコードを実行するためには APIC-EM コントローラにアクセスできる必要があります自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を利用できます Always-On のサンドボックスのログインクレデンシャルはユーザ名 :devnetuser パスワード : Cisc123! です詳細は別途示します

2 ステップ 1:APIC-EM API リソースの確認このラボでは REST API の例として APIC-EM API を使用します始める前に APIC-EM リソースを DevNet で確認しておく必要があります 1. ブラウザで DevNet にアクセスします Web ページの右上にある [ ログイン (Lgin)] リンクをクリックしますログイン Web ページで自分のログインクレデンシャル (CCO ID) を入力し [ ログイン (Lg In)] ボタンをクリックします Cisc Cnnectin Online ID(CCO ID) を持っていない場合は [ 今すぐ登録 (Register Nw)] ボタンをクリックし指示に従いますログイン Web ページへ戻ってきたらクレデンシャルを入力します 2. APIC-EM の開発者用リソースに直接移動するには上部のメニューを使用します [ テクノロジー (Technlgies)] メニューにアクセスするには [ テクノロジー (Technlgies)] リンクをクリックしますメニューで [ ネットワーキング (Netwrking)] をクリックした後 [APIC-EM] をクリックします

3 3. これで APIC-EM の Web ポータルにログインできましたラボでの実習中には API リファレンスドキュメントは別のタブで開いてください

ステップ 2:REST Web サービスとは Web サービスとは Web サービスとは定義されたインターフェイスを介して 2 つのシステム間で情報をやり取りする際の方式です Web サービスの主な 2 つの種類は REST と SOAP です REST Web サービスとは REST はネットワークアプリケーションを設計する際のアーキテクチャスタイルです

4 ステップ 2:REST Web サービスとは Web サービスとは Web サービスとは定義されたインターフェイスを介して 2 つのシステム間で情報をやり取りする際の方式です Web サービスの主な 2 つの種類は REST と SOAP です REST Web サービスとは REST はネットワークアプリケーションを設計する際のアーキテクチャスタイルです REST Web サービスは HTTP リクエストのように簡単にコールできる Web サービスです RESTful インターフェイスでは通常 CRUD( 作成更新削除 ) の処理が提供されますさらに詳細を知りたい場合は REST チュートリアル [ 英語 ] を参照してください REST のメリット REST はプラットフォームを問わず簡単に使用できます

APIC-EM API は REST API ですこのラボでは APIC-EM API を使用します Applicatin Plicy Infrastructure Cntrl(APIC) エンタープライズモジュール (EM) アプリケーションプログラミングインターフェイス (API)(APIC-EM API) によりネットワークインフラストラクチャ全体にアプリケーションポリシーを導入し

5 APIC-EM API は REST API ですこのラボでは APIC-EM API を使用します Applicatin Plicy Infrastructure Cntrl(APIC) エンタープライズモジュール (EM) アプリケーションプログラミングインターフェイス (API)(APIC-EM API) によりネットワークインフラストラクチャ全体にアプリケーションポリシーを導入し実行することができます APIC-EM API を使用することでホストの一覧ネットワークデバイスの一覧ユーザの一覧などネットワーク上のデバイスに関する情報を取得できます Pythn から REST をコールする方法を学ぶための例としてこれらの機能を使用します APIC-EM のすべての機能の詳細については API リファレンスドキュメント [ 英語 ] を参照してください REST の仕組み REST は HTTP のリクエスト / レスポンスモデルの中核となるものです API の実行は HTTP リクエストのようにシンプルです

6 この例ではホストの一覧をリクエストしその情報がレスポンスで返りますレスポンスで返されるデータは通常は JSON か XML です (JSON:JavaScript Object Ntatin は人が判読可能な形式でデータ交換できるように設計されたテキストベースの軽量なオープンスタンダードです )

7 ステップ 3: リクエスト作成のために必要なことリクエストを作成するにはコールする API に関して次の情報が必要ですこの情報は API リファレンスドキュメントで確認できますメソッド URL GET: データを取得します POST: 新しいデータを作成します PUT: データを更新します DELETE: データを削除しますコールするエンドポイントの URL 例 : {APIC-EMCntrller} の部分は使用しているコントローラの IP もしくは DNS で引ける名前に置き換えられます自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用します URL パラメータ URL の一部として渡すパラメータのことです認証使用する認証の種類を知る必要があります Basic HTTP トークンベース OAuth が一般的な種類です認証のクレデンシャルカスタムヘッダー API が HTTP ヘッダーを送信する必要があるかを確認します例 :Cntent-Type:applicatin/jsn リクエストボディリクエストの処理に必要なデータを含んだ JSON や XML はリクエストのボディで送信することができます

8 認証について REST API の認証には一般的に 3 つの種類があります認証は REST API へのアクセス制御とアクセス権限に使用されますたとえば読み取り専用のアクセス権限を割り当てられているユーザの場合データを読み取る API だけをコールできることになりますデータの読み取りと変更 ( 追加編集削除 ) の両方が許可されているユーザの場合はすべての API をコールできますこれらのアクセス権限は通常ユーザに割り当てられたロールに基づいていますロールにはユーザがデータ変更に関するすべての権限をもつ管理者ロールや読み取り専用のアクセス権限をもつユーザロールなどがあります 1. Basic HTTP: ユーザ名とパスワードがエンコードされた文字列でサーバに渡されます詳細については Basic 認証 [ 英語 ] を参照してください 2. OAuth:HTTP 認証およびセッション管理のオープンスタンダード特定のユーザに関連付けられたアクセストークンを作成しユーザ権限も指定しますアクセスと制御の確認に API コールを実行する際ユーザと権限を特定するためにトークンが使用されます詳細については OAuth [ 英語 ] を参照してください 3. トークン :OAuth と同様にトークンが生成され API コールごとに渡されますただしサーバとクライアントとのやりとりをシンプルにするためクライアントのセッションの管理や追跡は行われません APIC-EM は認証管理にこの設計を使用します詳細についてはトークンベース認証 [ 英語 ] を参照してください APIC-EM はトークンベースの認証を使用しますしたがって最初に作成する必要のあるリクエストは APIC-EM でサービスチケットと呼ばれるトークンを作成するリクエストですサービスチケットは API へのアクセスの許可と制御の両方に使用されチケット作成のために実行されるコール以外のすべての API コールに必要になります APIC-EM の認証トークンを使用する手順は次のとおりです 1. チケットを作成します 2. チケット ( トークン ) がレスポンスのボディで返されます 3. これ以降のすべてのリクエストの X-Auth-Tken ヘッダーにこのトークンを含めます

9 API リファレンスドキュメントの使用 API リファレンスドキュメントではすべての API メソッドの一覧と各リクエストの作成方法の詳細について確認できます新しい API を使用する際には API リファレンスが最も重要な情報源の 1 つとなりますではここで APIC-EM のチケット API について確認してみましょう APIC-EM リファレンスドキュメントを開くとすべての API がスクロール可能な形式で表示されます [ ロールベースアクセス制御 (Rll Based Access Cntrl)] をクリックし [ チケット (ticket)] をクリックします

[ チケット (ticket)] で [POST] の [/ticket] をクリックしますこの API がチケット作成機能を持っていますレスポンスの内容 API リファレンスには送受信される情報のデータ属性が含まれています受信するデータはレスポンスの部分で定義されておりデータ形式や属性とともに HTTP

10 [ チケット (ticket)] で [POST] の [/ticket] をクリックしますこの API がチケット作成機能を持っていますレスポンスの内容 API リファレンスには送受信される情報のデータ属性が含まれています受信するデータはレスポンスの部分で定義されておりデータ形式や属性とともに HTTP ステータスコードが含まれています HTTP ステータスコード HTTP ステータスコードは成功失敗または他のステータスを返すために使用されます次のような例が一般的です 200 OK 202 Accepted/Prcessing 401 Nt Authrized

属性が含まれていることがわかりますこれが他のすべての API エンドポイントへの API コールの作成に必要なトークンの値になります [

11 内容を確認しサーバに送信されるデータやアプリケーションに返されるデータを把握します両方のデータを丸で囲っていますチケット作成リクエストのレスポンスの例ではレスポンスの文字列に文字列型の値として serviceticket 属性が含まれていることがわかりますこれが他のすべての API エンドポイントへの API コールの作成に必要なトークンの値になります [ パラメータ (Parameters)] セクションで [ モデルスキーマ (Mdel Schema)] をクリックします API を試す場合はこのボックスをクリックしてパラメータを編集可能なボックスに移します

12 確認事項 API リファレンスガイドの他のチケット API をチェックしどこが違うかを確認します

13 ステップ 4:REST の実行 : 実際に試す APIC-EM の例 :POST でのチケットの作成 API を使用して認証用チケットを作成する方法について詳しく説明しますリクエストを作成してサービスチケットを取得する方法を知るためには API のドキュメントを使用して次の内容を決定する必要がありますメソッド URL ヘッダー認証ボディ API-EM 用の URL はすべて次のように始まりますチケットの API コールの説明については APIC-EM API ドキュメント [ 英語 ] を参照してください POST /api/v1/ticket: 新しいユーザチケットの作成にはこのメソッドが使用されます HTTP コールでのサービスチケットの作成は非常に簡単ですサービスチケットを入手するリクエストは次のようになりますメソッド :POST URL: アドレス部分の {APIC-EM-Server} は使用する APIC-EM のアドレスで置き換えます自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用します

14 ヘッダー POST コールの場合は Cntent-Type にヘッダーで applicatin/jsn と指定する必要がありますすべての REST メソッド (GET POST PUT DELETE 等 ) コールでこのヘッダーを含めるのが一般的です認証この API コールでは認証データはボディに入れられて送信されますボディ APIC-EM コントローラへのログインに使用するユーザ名とパスワードは JSON 形式でボディに指定する必要があります

15 ステップ 5:REST API コール Web サービスを手軽にテストする上で役に立つ HTTP クライアントが多数ありますこれらのツールを使用すれば簡単に REST API のリクエストを作成して送信しレスポンスを確認できます Pstman: Firefx RestClient: curl を使用したコマンドライン : SOAPUI REST サービスのテスト機能が組み込まれた各種 IDE コンソールこのラボでは REST クライアントの例として Pstman を使用します使用前に SSL 証明書を受け入れます Pstman で API をコールする前に SSL 証明書を受け入れる必要があります証明書の警告が表示される場合はサンドボックスに移動し次の手順に従います警告が表示されない場合は省略できます 1. Chrme を開きます 2. DevNet の Always-On APIC-EM サンドボックスを使用している場合はに移動します 3. 証明書の問題を示すメッセージが表示された場合は [ 詳細 (Advanced)] リンクをクリックしますメッセージが表示されず APIC-EM UI のログイン画面に遷移する場合は Pstman を使用して REST API コールを発信するの項にスキップします

16 4. [ 進む (Prceed t)] のリンクをクリックします 5. APIC-EM のログイン画面が表示されますこれで Pstman で作業を開始できるようになりました

17 Pstman を使用して REST API コールを発信する 1. Chrme を起動し Pstman を開きます DevNet Zne のステーションにいる場合はすでに Pstman がインストールされています Ggle App Launcher から起動するか Chrme から Pstman をクリックして Launch App を実行し起動させることができますそれ以外の場合は Chrme ブラウザでこのページを表示していることを確認した上で上記の Pstman のリンクをクリックし指示にしたがって Pstman をインストール後起動してください 2. 次を参照して Pstman の該当するフィールドにホスト一覧を取得するリクエスト用の情報を入力しますメソッド URL A: メソッドのドロップダウンから [POST] を選択します B: と入力します自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用しますボディ C: ユーザ名とパスワードを JSON 形式で入力しますこれらのクレデンシャルは APIC-EM コントローラへのログインに使用されます DevNet の APIC-EM Always-On ラボにアクセスしている場合は上記のユーザ名とパスワードを入力しますそうでない場合は自分の APIC-EM コントローラに必要なユーザ名とパスワードを入力します

Pstman はサーバにリクエストを送信しレスポンスを表示します [ レスポンスコード (Respnse Cde)] が戻され [ ステータス (Status)]

18 ヘッダー A: ヘッダーに Cntent-Type applicatin/jsn と入力します認証上記のようにボディに指定された認証情報が使用されます 3. [ 送信 (Send)] をクリックします 4. Pstman はサーバにリクエストを送信しレスポンスを表示します [ レスポンスコード (Respnse Cde)] が戻され [ ステータス (Status)] フィールドに表示されるのを確認しますこの場合は 200 です serviceticket 属性を含む [JSON] レスポンスデータが表示されますサービスチケットの値をハイライトで示しています実際に返される値は示されているものとは異なります次のステップで使用するためにこの値をテキストファイルにコピーアンドペーストしますおめでとうございます最初の REST API コールを実行できました

19 ステップ 6: サービスチケットを使用した APIC-EM REST API コール APIC-EM の例 : ホストの取得ホストを取得する REST API コールについて説明しますホストはワークステーションなどのエンドデバイスですネットワークケーブルでスイッチなどのネットワークデバイスに接続されたりワイヤレスデバイスに接続されたりしますここでの目的はホストを見つけその情報を表示することですホスト一覧を取得するためのリクエスト方法を知るためには API のドキュメントを使用して次の内容を決定する必要がありますメソッド URL ヘッダー認証ボディ API のドキュメントで記述されているように API-EM 用の URL はすべて次のように始まりますホスト取得の API の詳細については APIC-EM API ドキュメント [ 英語 ] を参照してください下のコールによって指定されたサーバ上のすべてのホストが取得されます GET 一方表示上の理由からホストの一部だけを部分的に取得したい場合がありますその場合はたとえば受け取るホストの最大数を指定する limit パラメータを渡すことができますまた必要に応じてホストの一覧をどこから始めるかを指定する ffset パラメータを渡すこともできます下のコールでは最初のホストから開始し (ffset=1) 受け取るホストの最大数が 5 になるように指定しています (limit=5)

GET https://{apic-em-server}/api/v1/hst?

20 GET ホストの一覧をすべて取得する場合リクエストは次のようになりますメソッド :GET URL: アドレスは使用する APIC-EM コントローラのアドレスで置き換えます自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用しますヘッダー認証のため以前に作成したサービスチケットを追加する必要がありますヘッダーの左側で X-Auth-Tken というテキストを追加します右側にはエンドポイントへ Create Ticket をコールして戻ってきたサービスチケットの値を追加します GET を使用する際にはリクエストにコンテンツヘッダーは必要ありませんが実際にはコンテンツヘッダーで Cntent-Type に applicatin/jsn を指定することを推奨します認証上記のヘッダーで行いますボディこのリクエストには不要です

21 ステップ 7: ネットワークホストの取得 1. Pstman で API コールを設定しますここではコントローラからホストを取得するリクエストの認可にサービスチケットを使用します 2. 次を参照して Pstman の該当するフィールドにホスト一覧を取得するリクエスト用の情報を入力しますメソッド URL A: メソッドのドロップダウンから [GET] を選択します B: と入力します自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用しますヘッダー C: Cntent-Type と入力し値に applicatin/jsn を指定します C: X-Auth-Tken と入力し以前作成したサービスチケットの値を指定します X-Auth-Tken は APIC-EM コントローラのすべての API コールに必要です認証ヘッダーで行いますボディこのリクエストには不要です 3. [ 送信 (Send)] をクリックします 4. Pstman はサーバにリクエストを送信しレスポンスを表示します

22 [ レスポンスコード (Respnse Cde)] が返され [ ステータス (Status)] フィールドに 200 OK と示されているのを確認できます返されたホストの一覧を含む JSON を確認できます確認事項 1. Pstman での URL に?limit=1&ffset=1 を追加し EMCntrller}/api/v1/hst?limit=1&ffset=1 として [ 送信 (Send)] ボタンを押しますこの場合返ってくるデータはどこが違うでしょうかホスト取得 API コールの詳細については API リファレンスガイドを確認してくださいおめでとうございます APIC-EM サービスチケットを使用する最初の REST API コールを実行できました

ステップ 8: ネットワークデバイスの取得ネットワークデバイスを取得する REST API コールについて説明しますネットワークデバイスはホストデバイスや他のネットワークデバイスとの間でデータを送受信します通常ネットワークデバイスはハブスイッチルータでイーサネットケーブルで接続するかワイヤレスで接続することができますここでの目的はネットワークデバイスを見つけ

23 ステップ 8: ネットワークデバイスの取得ネットワークデバイスを取得する REST API コールについて説明しますネットワークデバイスはホストデバイスや他のネットワークデバイスとの間でデータを送受信します通常ネットワークデバイスはハブスイッチルータでイーサネットケーブルで接続するかワイヤレスで接続することができますここでの目的はネットワークデバイスを見つけその情報を表示することですネットワークデバイスを取得する API の詳細については APIC-EM API ドキュメント [ 英語 ] を参照してください 1. Pstman で API コールを設定しますここではコントローラからネットワークデバイスを取得するリクエストの認可にサービスチケットを使用します 2. 次を参照して Pstman の該当するフィールドにネットワークデバイス一覧を取得するリクエスト用の情報を入力しますメソッド A: メソッドのドロップダウンから [GET] を選択します URL B: と入力します自分の APIC-EM コントローラを使用しない場合は Always-On APIC-EM ラボ ( を使用しますヘッダー C: Cntent-Type と入力し値に applicatin/jsn を指定します C: X-Auth-Tken と入力し以前作成したサービスチケットの値を指定します X-Auth-Tken は APIC-EM コントローラのすべての API コールに必要です

24 認証ヘッダーで行いますボディこのリクエストには不要です 3. [ 送信 (Send)] をクリックします 4. Pstman はサーバにリクエストを送信しレスポンスを表示します [ レスポンスコード (Respnse Cde)] が返され [ ステータス (Status)] フィールドに 200 OK と示されているのを確認できます返されたホストの一覧を含む JSON を確認できます下のような出力が表示されます表示上の理由で何行かのレコードは削除されています

25 確認事項 Pstman での URL に 1/2 を追加しとして [ 送信 (Send)] ボタンをクリックしますこの場合出力はどこが違うでしょうか今実施したネットワークデバイスを取得する API コールでの違いとステップ 7 の演習で実施したホストを取得するコールでの違いを比較しますどのように異なっているでしょうかまたそれはなぜでしょうかヒント : これらの API コールについてそれぞれ API リファレンスガイドを確認します Pstman で API コールをからに変更し [ 送信 (Send)] ボタンを押します返ってくるデータがどのように変わり何を表していますかヒント :API リファレンスガイドを確認します

API( アプリケーションプログラミングインターフェイス ) は 2 つのソフトウェアが相互に通信する際の方式ですあなたは通常ソフトウェアとのインターフェイスにどのようなものを使用しているでしょうかたとえば Web ブラウザ (Web インターフェイス ) を開いて電子メールにアクセスしている

API( アプリケーションプログラミングインターフェイス ) は 2 つのソフトウェアが相互に通信する際の方式ですあなたは通常ソフトウェアとのインターフェイスにどのようなものを使用しているでしょうかたとえば Web ブラウザ (Web インターフェイス ) を開いて電子メールにアクセスしているご利用のコンピュータを設定する方法事前設定された dcloud ラボを使用してこのラボに取り組む場合はイベントの事前準備 [ 英語 ] とラボの設定 [ 英語 ] の両モジュールを確認してください自身のコンピュータでこのラボの作業を行うには Postman という Chrome http クライアントをインストールする必要がありますまた Spark アカウントも必要です REST API の基本

ステップ 1:APIC-EM API リソースの確認 このラボでは REST API の例として APIC-EM API を使用します 始める前に APIC-EM リソースを DevNet で確認しておく必要があります 1. ブラウザで DevNet にアクセスします Web ページの右上にある [

ステップ 1:APIC-EM API リソースの確認このラボでは REST API の例として APIC-EM API を使用します始める前に APIC-EM リソースを DevNet で確認しておく必要があります 1. ブラウザで DevNet にアクセスします Web ページの右上にある [