使用する前に
使用する前に

使用する前に

この章は、次の内容で構成されています。

API アクセス キーの概要

API インターフェイスを通じて Cisco UCS Director にアクセスするには、有効な Cisco UCS Director ユーザ アカウントと API アクセス キーが必要です。 API アクセス キーは Cisco UCS Director による API 要求の認証に必要です。 このアクセス キーは、特定の有効な Cisco UCS Director ユーザ アカウントに関連付けられた一意のセキュリティ アクセス キー コードです。

API 要求を認証するため、あらゆる Cisco UCS Director API で、認証に API アクセス キーが必要とされます。 標準の HTTP 構文および意味規則に従い、name:value ヘッダーとして REST API アクセス キーを渡す必要があります。 たとえば、有効な name:value のヘッダーの一例は、X-Cloupia-Request-Key: F90ZZF12345678ZZ90Z12ZZ3456FZ789 です。 API 要求ヘッダーの詳細については、要求の形式RFC2616 のヘッダー フィールド定義を参照してください。

データのセキュリティを保つため、あらゆる要求を HTTPs(SSL)接続で送信してください。

API アクセス キーの生成

手順
    ステップ 1   Cisco UCS Director で右上にあるログイン名をクリックします。

    たとえば、admin としてログインしている場合、Cisco UCS Director の右上に admin と表示されます。

    ステップ 2   [ユーザ情報] ダイアログ ボックスで、[詳細] タブをクリックします。
    ステップ 3   [REST APIアクセスキー] の領域に表示された値をコピーするには、[キー値のコピー] をクリックします。
    ステップ 4   安全な場所にアクセス キーを保存し、それを API 要求ヘッダーで使用します。

    API 要求ヘッダーの詳細については、要求の形式を参照してください。

    ステップ 5   API アクセス キーを変更する場合には、[キーの再生成] をクリックします。

    新しいキーの生成後は、古いキー コードは無効になり、使用できなくなります。


    開発者メニュー オプションの有効化

    Cisco UCS Director には、開発者や技術者用に特別に用意された機能があります。 開発者メニュー オプションを有効にした後、総合的な REST API ブラウザおよびレポート メタデータ情報にアクセスすることができます。 これらの機能によって、サイト固有の API データと、任意の標準 HTTP または HTTPS ブラウザから送信できる REST API 要求コードが提供されます。 レポート メタデータ ビューから提供される HTTP 要求コードを使用すれば、API サービス結果をすぐに得られます。 API 情報が必要なあらゆる状況でこれらのオプションを使用できます。

    Cisco UCS Director REST API ブラウザは、API 情報および API コード生成機能を提供し、REST API と Java API の両方を含む利用可能なあらゆる API を見やすく表示し、作業を促進します。

    はじめる前に

    アプリケーション ユーザに付与されるものとまったく同じデータへの管理アクセス権を提供する 1 つ以上のユーザ アカウントを取得します。 異なる管理者およびエンドユーザのロールに関連付けられたデータ アクセスの制限については、Cisco UCS Director の管理者にお問い合わせください。 異なるデータ アクセスとセキュリティ制御に関連付けられたユーザ体験をテストするために、複数のユーザ アカウントが必要な場合があります。

    手順
      ステップ 1   Cisco UCS Director で右上にあるログイン名をクリックします。

      たとえば、admin としてログインしている場合、Cisco UCS Director の右上に admin と表示されます。

      ステップ 2   [ユーザ情報] ダイアログ ボックスで、[詳細] タブをクリックします。
      ステップ 3   [[開発者]メニューの有効化(このセッション)] チェックボックスにチェックを入れて、[ユーザ情報] ダイアログ ボックスを閉じます。

      現在のセッションの間中、[REST APIブラウザ] が有効になり、このセッションで開かれるレポート ビューで [レポートメタデータ] オプションが利用可能になります。

      ヒント   

      [詳細] タブにはアカウントの REST APIアクセスキー コードも表示されます。

      ステップ 4   [ユーザ情報] ダイアログ ボックスを閉じます。

      REST API ブラウザの使用

      Cisco UCS Director REST API ブラウザは、XML 形式の REST API および Java API を含むすべての利用可能な公開 Cisco UCS Director API の使用において開発者に支援と教育を提供する、API 情報および API コード生成機能を提供します。 プライマリ ビューにはタスク フォルダがリストされ、そのそれぞれが API へのアクセスを提供します。 タスク名は最上位のコンテキストまたはカテゴリ フォルダを効果的に表し、その下に API がリストされています。 たとえば、NetApp ONTAP タスクおよび NetApp OnCommand タスクに関連するすべての API は、これらの名前が付いたフォルダの中にあります。

      はじめる前に
      • アプリケーション ユーザに付与されるものとまったく同じデータへの管理アクセス権を提供する 1 つ以上のユーザ アカウントを取得します。 異なる管理者およびエンドユーザのロールに関連付けられたデータ アクセスの制限については、Cisco UCS Director の管理者にお問い合わせください。 異なるデータ アクセスとセキュリティ制御に関連付けられたユーザ体験をテストするために、複数のユーザ アカウントが必要な場合があります。

      • セッションの開発者メニュー オプションを有効にします。

      手順
        ステップ 1   メニュー バーで、[ポリシー] > [オーケストレーション] の順に選択します。
        ステップ 2   [REST APIブラウザ] タブをクリックします。

        必要に応じて、右のスクロール矢印をクリックし、[REST APIブラウザ] タブに移動します。

        ステップ 3   表示する API を含むタスク フォルダを開きます。
        ヒント   

        特定の API がどのタスク フォルダに属するか分からない場合には、[REST APIブラウザ] タブの右上隅にある [検索] フィールドを使用して検索できます。 API の [リソース]、[操作]、または [説明] フィールドに含まれる文字列を入力して検索を絞り込みます。 また、[高度な検索フィルタを追加] など、メニュー バーにある他のオプションを使用して特定の API を検索することもできます。

        ステップ 4   関心のある API リソースと操作を含む行をダブルクリックします。

        REST API ブラウザには次が表示されます。

        • [APIの例] タブ:選択された API データが表示され、サンプル URL を生成することができます。 選択された操作とリソースに基づいて、このタブにはパラメータ値を入力し、適切な API リクエストを作ることができるデータ入力ボックスも含まれる場合があります。 データ入力ボックスで利用可能な場合、[選択...] をクリックすると、データ検索フィルタが開き、入力する必要があるデータを絞り込み、選択することができます。

        • [詳細] タブ:API の定義、入力パラメータ、出力パラメータを含む API についての追加情報が表示されます。

        • [サンプル Java コード] タブ:API のサンプル コードが表示されます。


        レポート メタデータへのアクセス

        レポート メタデータを使用すると、Cisco UCS Director で表示される各レポートの API 要求コードを含む、Cisco UCS Director によって使用される API コードを確認することができます。 このコードには、すぐにブラウザに貼り付けて送信できる完全な URL コードが含まれます。 直接の API 応答は開発者に豊富な情報と教育を提供します。 API 要求コードを確認するには、レポートに移動して、[レポートメタデータ] を選択し、表示されたリストをレポートの取得に使用された API 要求まで下にスクロールします。

        はじめる前に
        • アプリケーション ユーザに付与されるものとまったく同じデータへの管理アクセス権を提供する 1 つ以上のユーザ アカウントを取得します。 異なる管理者およびエンドユーザのロールに関連付けられたデータ アクセスの制限については、Cisco UCS Director の管理者にお問い合わせください。 異なるデータ アクセスとセキュリティ制御に関連付けられたユーザ体験をテストするために、複数のユーザ アカウントが必要な場合があります。

        • セッションの開発者メニュー オプションを有効にします。

        手順
          ステップ 1   Cisco UCS Director で API コードを確認するページに移動します。

          たとえば、次のいずれかを選択します。

          • [ポリシー] > [オーケストレーション]

          • [物理] > [ストレージ] > [Storage_Account] > [ファイラ]

          ステップ 2   [レポートメタデータ] をクリックします。
          ステップ 3   [情報] ダイアログ ボックスでサンプル コードを確認します。

          要求の形式

          API クライアントは HTTP または HTTPS を使用して Cisco UCS Director と対話できます。 REST API アクセス キーをパスするには、各要求が X-Cloupia-Request-Key と呼ばれる http/https ヘッダーと関連付けられており、その値が現在の REST API アクセス キーに設定されている必要があります。 このキーの取得と使用については、API アクセス キーの生成を参照してください。

          URL の形式

          http://SERVER/app/api/rest?formatType=json&opName=operationName&opData=operationData

          ここで SERVERCisco UCS Director VM のホスト名の IP アドレスで、

          opName は要求に関連付けられた API 操作の名前です。 例:userAPIGetMyLoginProfile、または userAPIGetVMActionStatus

          ここで opData には JSON パラメータ(操作に関連付けられた引数)が含まれます。

          URL 要求パラメータ

          • formatType:ここで説明するサポートされる形式は JavaScript Object Notation(JSON)のみです。 このパラメータ値を json に設定します。

          • opName:要求に関連付けられた操作の名前です。 操作のリストは REST API の操作の概要に記載されています。

          • opData:操作に関連付けられたパラメータ(または引数)です。 Cisco UCS Director はパラメータの JSON エンコーディングを使用します。 操作に引数が必要ではない場合、空のセットとして {} を使用します。 要求で JSON データを送信する前に、必要に応じてエスケープ文字を適用する必要があります。 URL エンコーディングの詳細については、http:/​/​www.ietf.org/​rfc/​rfc1738.txt の RFC を参照してください。

            JSON 構文とデータ タイプの詳細については、http:/​/​en.wikipedia.org/​wiki/​JSON#Data_​types.2C_​syntax_​and_​example を参照してください。

          JSON 以外の形式の API 要求については、REST API ブラウザの使用を参照してください。

          操作のデータ パラメータ/引数の概要

          メソッドと API リソースの汎用指定は opName を通じて伝えられるため、操作のパラメータは操作を行うリソースの特定のインスタンスを指定するために必要なあらゆる引数を提示する必要があります。

          利用可能な API の操作とパラメータ仕様のリストは、REST API の操作の概要を参照してください。

          操作データ パラメータ構文

          次の表に JSON 形式の操作データ パラメータ構文の例を示します。

          操作に次のパラメータが必要か否か(opData) JSON で表す方法

          パラメータなし

          {}

          1 つのパラメータ:整数(例:10)

          {param0:10}

          1 つのパラメータ:文字列(例:cloud)

          {param0:"cloud"}

          2 つのパラメータ:文字列と整数

          {param0:"cloud",param1:10}

          2 つのパラメータ:null 値の文字列と整数

          {param0:null,param1:10}

          3 つのパラメータ

          {param0:"cloud",param1:"cloupia",param2:100}

          操作データ パラメータ

          …&opData={param0:"datacenter",param1:"DataCenter1",param2:"STORAGE-ACCOUNTS-T51"

          …&opData= {param0:"Create NFS Datastore",param1:{"list":[{"name":"Volume Size","value":100},{"name":"Select Group","value":"14"},{"name":"Select vDC","value":18}]},param2:212}

          • param0:REST API 経由で呼び出されるワークフローの名前。

          • param1:ワークフローに渡される入力。 複数の入力が存在する場合は、それらを引用符で囲んでから、カンマで区切って、中括弧内に入れます。 入力が存在しない場合は、API 呼び出しで null を使用します。

          • param2:このワークフローが他のサービス要求の子ワークフローとして呼び出される場合は、サービス要求(SR)ID を使用します。 このワークフローが子ワークフローとして呼び出されない場合は、-1 を使用します。 -1 を使用した場合は、新しいサービス要求が呼び出されます。


          ヒント


          Cisco UCS Director は、URL 形式で切り取ってブラウザに貼り付けることができる、多くの完全な API 要求を提供します。 開発者メニュー オプションの有効化を参照してください。


          コンテキスト パラメータ

          上の例で、Param0Cisco UCS Directorコンテキストを指定するために使用されます。 コンテキスト データ値は Cisco UCS Director によって管理される主要なドメイン("global-services""vm""vdc""datacenter""storage_accounts""Compute-chassis""network-device" など)の 1 つを意味します。 標準の Cisco UCS Director コンテキストのリストは API 要求コンテキスト パラメータ に記載されています。

          レポート パラメータ

          レポート パラメータ値は常に reportId です。 一般的な reportId には、"STORAGE-ACCOUNTS-T51""CPU-S0"、"VOLUMES--X1""NETWORK-USAGE-H0""PORT-SUMMARY-V50""PRIVATE-CLOUD-FREE-STORAGE-S1" が含まれます。 通常、reportId は、レポートの API 要求のパラメータ リストの最後のパラメータです。 よって、コンテキストが 2 つのパラメータで指定されている場合には、通常レポート パラメータは 3 つ目の param2 です。 コンテキスト別にカテゴリ分けされた、レポート名、reportId の包括的なリストは、利用可能な Cisco UCS Director レポートのリストを参照してください。

          サンプル API 要求 1

          ログイン プロファイルを要求する操作はログインしているユーザを参照するため、パラメータは必要ありません。 ほとんどのその他の操作は複数の引数を必要とします。

          http://10.10.1.153/app/api/rest?formatType=json&opName=userAPIGetMyLoginProfile&opData={}
          { "serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith","email":"jsmith@example.com",
           "groupName":"Eng Group","role":"Regular"}, "serviceError":null, 
          "serviceName":"InfraMgr", "opName":"userAPIGetMyLoginProfile" }

          サンプル API 要求 2

          データセンターのシャーシに関するレポートのこの要求では、操作に 3 つのパラメータが必要であり、これはレポートの要求では一般的です。

          http://172.99.999.142/app/api/rest?opName=userAPIGetTabularReport&opData={param0:"datacenter",
           param1:"datacenter",param2:"UCS-CHASSIS-T50"}
          { "serviceResult": 
              {"rows":[{"ID":"PHY-ACC;sys/chassis-2",
              "Account_Name":"PHY-ACC","DN":"sys/chassis-2",
              "Serial_Number":"1558","Model":"N20-C6508","Power_State":"ok",
              "Operation_State":"accessibility-problem",
              "Configuration_State":"ok","License_State":"license-ok","Servers":5,
              "IO_Modules":2,"PSUs":4,"Fan_Modules":8,
              "Vendor":"Cisco Systems Inc"},{"ID":"UCSCirrus;sys/chassis-1",
              "Account_Name":"UCSCirrus","DN":"sys/chassis-1",
              "Serial_Number":"FOX1352GDX4","Model":"N20-C6508",
              "Power_State":"redundancy-failed","Operation_State":"power-problem",
              "Configuration_State":"ok","License_State":"license-ok","Servers":7,
              "IO_Modules":2,"PSUs":4,"Fan_Modules":8,
              "Vendor":"Cisco Systems Inc"},{"ID":"UCSM237;sys/chassis-1",
              "Account_Name":"UCSM237","DN":"sys/chassis-1",
              "Serial_Number":"1557","Model":"N20-C6508","Power_State":"ok",
              "Operation_State":"operable",
              "Configuration_State":"unsupported-connectivity","License_State":"license-ok",
              "Servers":6,"IO_Modules":2,
              "PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"},
              {"ID":"real108;sys/chassis-1","Account_Name":"real108",
              "DN":"sys/chassis-1","Serial_Number":"FOX1352GDX4","Model":"N20-C6508",
              "Power_State":"redundancy-failed",
              "Operation_State":"power-problem","Configuration_State":"ok",
              "License_State":"license-ok","Servers":7,
              "IO_Modules":2,"PSUs":4,"Fan_Modules":8,"Vendor":"Cisco Systems Inc"}],
            "columnMetaData":null}, "serviceError":null, "serviceName":"InfraMgr", 
             "opName":"userAPIGetTabularReport" }}

          ヒント


          上級 Cisco UCS Director API ユーザ向け:データセンターの UCS-CHASSIS-T50 レポートのレポート メタデータ要求内に含まれるコードでは、最初のパラメータが param0:"23" になっています。 サンプル API 要求 2 で使用された要求では、コンテキスト "datacenter" が値 "23" で置き換えられ、要求は成功しました。 API ドキュメンテーションをレポート メタデータおよび Cisco UCS Director と比較すると、レポート メタデータ 要求内に現れるアルファベットの文字列の値が(コンテキストを表す)数字の文字列の値で置き換えられることが分かります。


          応答の形式

          次の HTTP ステータス コードが Cisco UCS Director より返されます。

          • 401 Unauthorized:API キーが無効です。

          • 200 OKCisco UCS Director は要求を処理しました。 要求の実際のステータスは応答の本文に含まれます。

          Cisco UCS Director の応答の本文は JSON 形式です。これは API 要求で指定された FormatType パラメータにより決定されます。

          API 応答のコンポーネント

          API 応答のコンポーネント 説明 コンポーネント例(成功のシナリオ)

          serviceResult

          要求が成功すると、この結果には指定された名前/値ペアのセットまたは JSON オブジェクト、あるいはレポートが含まれます。

          "serviceResult":
          {"userId":"jsmith",
          "firstName":"John","lastName":"Smith",
          "email":"jsmith@example.com",
          groupName":"Eng Group","role":"Regular"}

          serviceError

          要求が成功すると、serviceError が null に設定されます。 操作が失敗すると、serviceError には実際のエラー メッセージが含まれます。

          "serviceError":null

          serviceName

          バック エンド サービスの名前です。 たとえば、往々にして InfraMgr に設定されています。

          "serviceName":"InfraMgr"

          opName

          要求で提供された操作の名前です。

          "opName":"userAPIGetMyLoginProfile"

          例:成功シナリオでの API 応答

          {
          "serviceResult":{"userId":"jsmith","firstName":"John","lastName":"Smith",
          "email":"jsmith@example.
          com","groupName":"Eng Group","role":"Regular"}, "serviceError":null, 
          "serviceName":"InfraMgr",
          "opName":"userAPIGetMyLoginProfile" 
          }
          

          例:失敗シナリオでの API 応答

          { "serviceResponse":null, 
          "serviceError":"SERVICE_CALL_EXCEPTION: Service InfraMgr does not support operation test", 
          "serviceName":"InfraMgr", "opName":"test" 
          }

          API 応答(サービス結果)データ タイプ

          Cisco UCS Director REST API 要求への応答で送信されるサービス結果(ペイロード)はその操作向けに指定されています。 サービス結果は操作に特化した名前/値ペアのセット、またはこの API の標準データ タイプ、つまりレポートまたは JSON オブジェクトとしてフォーマットされている場合があります。

          各種レポート タイプの例は、レポートおよび JSON オブジェクト応答サンプルを参照してください。

          最も一般的に使用される Cisco UCS Director レポート形式およびそれらの内容についての情報は、レポートの概要を参照してください。

          利用可能なレポートおよびそれらに関連付けられているコンテキストのリストについては、利用可能な Cisco UCS Director レポートのリストを参照してください。

          JSON オブジェクトのサンプルについては、JSON オブジェクト パラメータ タイプを参照してください。