Cisco SD- WAN Cloud での Cisco API の使用

Cisco SD- WAN Cloud 用 Cisco API に関する情報

この章では、Cisco SD- WAN Cloud リリース 20.15 以降で、Cisco SD- WAN Cloudファブリック上の Cisco API にアクセスし、これらを使用する方法について説明します。

Cisco SD- WAN Cloud のお客様が Cisco API にアクセスするには、 API キーまたは JSON Webトークン（JWT）が必要です。

キーは、指定されたファブリックユーザーによる Cisco API の呼び出しに使用され、このユーザーが削除されるか、ユーザーロールが変更されるまで有効です。

Cisco API キーの取得

Cisco SD-WAN Cloud リリース 20.15 は、API キーを直接生成するメカニズムを提供します。次の手順に従って API キーを生成し、ゲートウェイ URL とクロスサイト リクエスト フォージェリ保護（CSRF）トークンの値を見つけます。

手順

ステップ 1

ファブリックにログインします。

ステップ 2

ユーザー ID の下にあるドロップダウンメニューから [My Profile] を選択します。

ステップ 3

[Profile] ページで、[API token] の下にある [Generate] をクリックします。API キーが生成され、表示されます。

ステップ 4

キーの内容をコピーまたはダウンロードします。

生成された API キーの例：

{
  "token": "eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA",
  "sub": "example@example.com",
  "iss": "b8edab9d-aaaa-4019-9999-f980cd5df3af",
  "aud": "vmanage",
  "userGroup": "[tenantadmin]",
  "tenant": "kdk-va2 - 999999-va-7aaaaaa5 - 640565",
  "duration": 315360000,
  "exp": 2058818495,
  "csrf": "AB0E71CAE...",
  "isAPIKey": true
}

ステップ 5

ここで提供されるエンドポイント情報を使用して、API ゲートウェイ URL を見つけます。ペイロード "org" フィールドに、API キーからの "tenant" 値を入力し、"apikey" フィールドに "token" 値を入力します。

例:

投稿 
https://ssp.sdwan.cisco.com/ssp/api/v6/apigw/info/
ペイロード
{ 
"org": "kdk-va2 - 999999-va-7aaaaaa5 - 640565", 
"apikey": "eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA", 
"is_redirect": false 
}
応答
{ 
"gateway_url": "apigw1clouduswest2-1024.viptela.info", 
"org": "kdk-va2 - 999999-va-7aaaaaa5 - 640565" 
}

（注）  

 

新しい API ゲートウェイがお客様の地理的な場所から近い場所にプロビジョニングされている場合は、このプロセスを繰り返して、オーバーレイを提供している新しいゲートウェイに接続します。

ステップ 6

受信した API キーとゲートウェイ URL ホスト名の値を使用して、エンドポイント “/dataservice/client/token” に GET 要求を送信して、受信した応答に含まれている CSRF トークンを取得します。この例で返されたゲートウェイ URL に基づくと、完全なパス名は https://apigw1clouduswest2-1024.viptela.info/dataservice/client/token となります。

Cisco API キーの使用に関する制限事項

Cisco API キーを使用すると、SSO ログインを介して Cisco SD- WAN Cloud からすべての Cisco API にアクセスできますが、いくつかの制限事項があります。Cisco API の詳細については、Cisco DevNet を参照してください。

  • 認証方法

    ヘッダーフィールドでベアラートークン認証方式を指定する必要があります。GET 要求から受け取った値を使用します。

  • クロスサイト リクエスト フォージェリ（CSRF/XSRF）に対する保護

    クロスサイト リクエスト フォージェリから保護するため、API リクエストヘッダーに X-XSRF-Token ヘッダーフィールドを含める必要があります。GET 要求から受け取った値を使用します。

  • API 本文の使用

    実行する API 呼び出しに基づいて、必要に応じて API 本文を含めることができます。

  • Rate limit

    リアルタイム API と一括 API は使用できません。他のすべての API を使用できますが、毎秒 10 件のレート制限の対象となります。Cisco SD- WAN Manager では、1 秒あたり 5 件の API レート制限が課されます。

  • 継続的な監視

    継続的な監視にはこの機能を使用しないでください。API レート制限の詳細については、『Cisco Catalyst SD- WAN スタートアップガイド』を参照してください。

  • サポートされているカテゴリ

    API 呼び出しは、次のカテゴリの操作に対してのみ提供されます。

    • 証明書管理

    • 設定

    • デバイスおよびデバイスインベントリ

    • モニタリング

    • トラブルシューティング ツール

  • NAT 構成非対応

    REST API を使用した NAT 構成はサポートされていません。

Cisco API 要求の例

このセクションの例は、API キー、ゲートウェイ URL、および CSRF/XSRF トークンを使用して API コールを実行する方法を示しています。

Curl を使用した GET API 要求の例

この GET 要求は、location パラメータで指定された URL のページを取得します。

curl --location apigw1clouduswest2-1024.viptela.info/dataservice/settings/configuration/banner'
--header 'X-XSRF-Token: AB0E71CAE...'
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA'

Curl を使用した PUT/POST API 要求の例

この PUT 要求は、data パラメータのデータを location パラメータで指定されたページ URL に送信します。

curl --location --request PUT apigw1clouduswest2-1024.viptela.info/dataservice/settings/configuration/banner'
--header 'X-XSRF-Token: AB0E71CAE72C6D...'
--header 'Content-Type: application/json'
--header 'Authorization: Bearer eyJ0eXAiOiJqd3QiLCJhbGciOiJSUzI1NiJ9.eyJzdWIiOiJ2bGluZ2FtcEBjaXNjby5jb20iLCJpc3MiOiJiOGVkYW
...
a_fcNoeAlVYvrXzDXA'
--data '{"mode":"on","bannerDetail":"check"}'