この製品のマニュアルセットは、偏向のない言語を使用するように配慮されています。このマニュアルセットでの偏向のない言語とは、年齢、障害、性別、人種的アイデンティティ、民族的アイデンティティ、性的指向、社会経済的地位、およびインターセクショナリティに基づく差別を意味しない言語として定義されています。製品ソフトウェアのユーザーインターフェイスにハードコードされている言語、RFP のドキュメントに基づいて使用されている言語、または参照されているサードパーティ製品で使用されている言語によりドキュメントに例外が存在する場合があります。シスコのインクルーシブランゲージに対する取り組みの詳細は、こちらをご覧ください。
このドキュメントは、米国シスコ発行ドキュメントの参考和訳です。リンク情報につきましては、日本語版掲載時点で、英語版にアップデートがあり、リンク先のページが移動/変更されている場合がありますことをご了承ください。あくまでも参考和訳となりますので、正式な内容については米国サイトのドキュメントを参照ください。
この章は、次の項で構成されています。
Cisco UCS Director REST API を使用すると、アプリケーションは Cisco UCS Director とプログラム的に対話できるようになります。REST API リクエストによって、Cisco UCS Director のリソースにアクセスできます。API コールを使用すると、Cisco UCS Director ワークフローを実行し、スイッチ、アダプタ、ポリシー、およびその他のハードウェアおよびソフトウェア コンポーネントの構成に変更を加えることができます。
開発環境のセットアップ方法の詳細については、『Cisco UCS Director REST API Getting Started Guide』を参照してください。
記述表題の下で、例はそれぞれ次のセクションから構成されます。
例が設計された目的。
いつ例を使用するか、使用しないか、およびその理由。
例を機能させるために必要な条件。
REST API を渡すための REST URL。
例で使用されるオブジェクトとメソッド、表示される入力変数。
例のコード。
例のコードから想定される出力。
例を実行するときは、変更内容を含める必要がある場合があることに注意してください。
関連する例
このマニュアルは、Cisco UCS Director Orchestrator で使用するサーバ側のスクリプト ソリューションである REST API を使用する際に役立つ例のコレクションです。手順書と同様に、少なくとも 3 つの方法でこのマニュアルを使用できます。
記載されているとおりに例に従うことで(もちろん使用する変数に置き換えて)、従う手順のすべてを把握していなくてもタスクを完了することができます。
テンプレートとして例を使用し、ワーク内の同様のタスクに適合させることができます。
例を検討することで、REST API Javadoc の参照とともに、REST API で「どのようなことが行われるか」について把握でき、スクリプトを作成する必要があるその他のタスクでの異なるメソッドの使用について概要を把握できます。
例は、一般的な使用例を説明するために選択されています。その目的はこれらの 3 つのすべての方法で円滑に使用できるようにすることです。
この例は、ユーザが仮想マシン(VM)をセルフ プロビジョニングするための単純なタスクを実行するために REST API を使用する方法を示しています。
この使用例に関係する REST API コールを要約し、要求およびシステム応答について詳しく説明します。応答は一般的に実装と一致しますが、Cisco UCS Director データベースの状態によっては完全に一致するわけではありません。必要なパラメータを応答から取得し、API 要求を通じてアプリケーションに渡す必要があります。
事前定義されたカタログ項目を使用して仮想マシン(VM)をプロビジョニングできます。これを行うには、カタログのリストを表示して、適切なサービス コンテナ カタログを選択する必要があります。選択したカタログを使用してサービス コンテナを作成し、サービス コンテナで VM をセルフプロビジョニングするためのサービス要求を送信できます。
UserAPIGetAllCatalogs:クラウド名とグループ名を含むカタログのリストを取得して、VM をプロビジョニングするカタログを選択します。
UserAPIServiceContainerCatalogRequest:選択したカタログを使用して VM をプロビジョニングするためのサービス コンテナを作成するサービス リクエストを送信します。
UserAPIGetServiceRequestWorkFlow:オプション。サービス リクエストのワークフローの詳細を表示します。
userAPISubmitServiceRequest:VM をプロビジョニングするサービス リクエストを送信します。
ステップ 1 | userAPIGetAllCatalogs API を使用して、VM がバインドされているクラウド名とグループ名を含むカタログのリストを取得します。その後、返されるリストからカタログを選択できます。 要求 /app/api/rest?formatType=json&opName=userAPIGetAllCatalogs&opData={}応答 { "serviceResult":{"rows":[{"Catalog_ID":"5","Catalog_Name":"VNX_Pranita","Folder":"Advanced","Catalog_Type":"Advanced", "Template_Name":"Not Applicable","Catalog_Description":"","Cloud":"","Image":"","Group":"Default Group","Icon": "/app/images/temp/1436492144835_ibm.png","OS":"","Additional_OS_Info":"","Applications":"","Additional_Application_Details":"", "Status":"OK"},{"Catalog_ID":"6","Catalog_Name":"MSP_CAT","Folder":"Advanced","Catalog_Type":"Advanced","Template_Name":"Not Applicable", "Catalog_Description":"","Cloud":"","Image":"","Group":"Default Group","Icon":"/app/images/temp/1436492144835_ibm.png","OS":"","Additional_OS_Info":"","Applications":"", "Additional_Application_Details":"","Status":"OK"},{"Catalog_ID":"7","Catalog_Name":"VNX_Update_Tenant","Folder":"Advanced", "Catalog_Type":"Advanced","Template_Name":"Not Applicable","Catalog_Description":"","Cloud":"","Image":"","Group":"Default Group", "Icon":"/app/images/temp/1436492144835_ibm.png","OS":"","Additional_OS_Info":"","Applications":"","Additional_Application_Details":"", "Status":"OK"},{"Catalog_ID":"8","Catalog_Name":"Pja_cat","Folder":"Advanced","Catalog_Type":"Advanced","Template_Name":"Not Applicable", "Catalog_Description":"","Cloud":"","Image":"","Group":"Default Group","Icon":"/app/images/temp/1436492144835_ibm.png", "OS":"","Additional_OS_Info":"","Applications":"","Additional_Application_Details":"","Status":"OK"}, {"Catalog_ID":"10","Catalog_Name":"pja_upd","Folder":"Advanced","Catalog_Type":"Advanced","Template_Name":"Not Applicable", "Catalog_Description":"","Cloud":"","Image":"","Group":"pja_sep","Icon":"/app/images/temp/1436492144835_ibm.png","OS":"", "Additional_OS_Info":"","Applications":"","Additional_Application_Details":"","Status":"OK"},{"Catalog_ID":"4","Catalog_Name":"zmn_con", "Folder":"Service Container","Catalog_Type":"Service Container","Template_Name":"zmnACT","Catalog_Description":"","Cloud":"","Image":"", "Group":"All Groups","Icon":"/app/images/temp/1436514875643_container_clear_64x64.png","OS":"","Additional_OS_Info":"","Applications":"", "Additional_Application_Details":"","Status":"OK"},{"Catalog_ID":"9","Catalog_Name":"ayc_LB","Folder":"Service Container","Catalog_Type": "Service Container","Template_Name":"aycACT","Catalog_Description":"","Cloud":"","Image":"","Group":"apREGsep9_org1","Icon": "/app/images/temp/1436514875643_container_clear_64x64.png","OS":"","Additional_OS_Info":"", "Applications":"","Additional_Application_Details":"","Status":"OK"},{"Catalog_ID":"11","Catalog_Name":"pja_con","Folder": "Service Container","Catalog_Type":"Service Container","Template_Name":"pja_tmp","Catalog_Description":"","Cloud":"","Image":"", "Group":"pja_sep","Icon":"/app/images/temp/1436514875643_container_clear_64x64.png","OS":"","Additional_OS_Info":"","Applications":"", "Additional_Application_Details":"","Status":"OK"},{"Catalog_ID":"12","Catalog_Name":"prsConCat","Folder":"Service Container", "Catalog_Type":"Service Container","Template_Name":"prsACT","Catalog_Description":"","Cloud":"","Image":"","Group":"arpAPIReg2_Org", "Icon":"/app/images/temp/1436514875643_container_clear_64x64.png","OS":"","Additional_OS_Info":"","Applications":"", "Additional_Application_Details":"","Status":"OK"}],"columnMetaData":null,"reportParams":{}}, "serviceError":null, "serviceName":"InfraMgr", "opName":"userAPIGetAllCatalogs" } |
ステップ 2 | VM をプロビジョニングし userAPIServiceContainerCatalogRequest API を使用してサービス リクエストを送信するためのサービス コンテナの作成に使用されるカタログ(pja_con など)を選択し、選択したカタログを使用してサービス コンテナを作成します。
この例では、SCN_Name と呼ばれるサービス コンテナが pja_con カタログを使用して作成されます。 要求/app/api/rest?formatType=json&opName=userAPIServiceContainerCatalogRequest&opData={param0: {"catalogName":"pja_con","groupName":"Default Group","serviceContainerName":"SCN_Name","apiResourceLimits": null,"networkThroughput":"1G","enableNetworkMgmt":true,"customTierLabels":[{"name":"web","value":"web"}], "comments":"test"}}応答 {"serviceResult":728, "serviceError":null, "serviceName":"InfraMgr", "opName":"userAPIServiceContainerCatalogRequest"}URL がサービス リクエスト ID を返します。サービス コンテナを作成するためのサービス リクエスト ID は 728 です。 |
ステップ 3 | (任意)サービス リクエストの作成後、userAPIGetServiceRequestWorkFlow API を使用してサービス要求に関する詳細および関連ワークフローの手順を取得します。SR ID(728)は、ステップ 2 の応答から渡されます。要求/app/api/rest?formatType=json&opName=userAPIGetServiceRequestWorkFlow&opData={param0:728}応答 { "serviceResult":{"requestId":728,"workflowCreated":1442274648591,"submittedTime":1442274648981,"cancelledTime":-1, "cancelledByUser":null,"adminStatus":1,"executionStatus":2,"futureStartTime":1442274648591,"entries":[{"stepId": "Initiated by aks","executionStatus":3,"statusMessage":null,"handlerId":4,"startedTime":-1,"completedTime":1442274649606, "validTill":-1,"startAfter":-1},{"stepId":"GetResourceRequirementFromThroughput","executionStatus":3,"statusMessage":"", "handlerId":12,"startedTime":-1,"completedTime":1442274657097,"validTill":-1,"startAfter":-1},{"stepId":"Allocate APIC Container Resources","executionStatus":2,"statusMessage":"Execution of the task resulted in errors","handlerId":12,"startedTime":-1, "completedTime":1442274662674,"validTill":-1,"startAfter":-1},{"stepId":"Verify Container Resource Limits","executionStatus":0, "statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"If Else", "executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1}, {"stepId":"APIC Reterive Secondary Container","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1, "completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Trigger APIC Container - DR Site","executionStatus":0,"statusMessage":null, "handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Create Tenant Application Profile", "executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1}, {"stepId":"Create Private Network ","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1, "validTill":-1,"startAfter":-1},{"stepId":"Trigger Multiple Container Tier Creation","executionStatus":0,"statusMessage":null, "handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Wait For Service Requests", "executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1}, {"stepId":"Setup APIC Container Network Connection","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1, "completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Create APIC Container Contracts","executionStatus":0,"statusMessage":null, "handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Child workflow (APIC Container Attached L4L7 Configuration)","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1, "validTill":-1,"startAfter":-1},{"stepId":"Provision APIC Container VMs","executionStatus":0,"statusMessage":null,"handlerId":12, "startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Re-Sync Container VMs","executionStatus":0,"statusMessage": null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"If Else","executionStatus":0, "statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Wait For Service Requests","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1}, {"stepId":"Child workflow (APICContainerSRMSettings)","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1, "completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Initiate APIC Container BM Provisioning","executionStatus":0,"statusMessage": null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId":"Send Container Email","executionStatus": 0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1,"startAfter":-1},{"stepId": "GetMSPAdminEmailAddresses","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime":-1,"validTill":-1, "startAfter":-1},{"stepId":"Send Container Email","executionStatus":0,"statusMessage":null,"handlerId":12,"startedTime":-1,"completedTime": -1,"validTill":-1,"startAfter":-1},{"stepId":"Complete","executionStatus":0,"statusMessage":null,"handlerId":13,"startedTime":-1, "completedTime":-1,"validTill":-1,"startAfter":-1}]}, "serviceError":null, "serviceName":"InfraMgr", "opName": "userAPIGetServiceRequestWorkFlow" }応答で、stepId はワークフローによって実行されるタスクを表します。ワークフローの実行が正常に完了すると、stepId は [完了(Complete)] として表されます。SCN_Name と呼ばれるサービス コンテナが作成されます。 |
ステップ 4 | VM をプロビジョニングするには、userAPISubmitServiceRequest API を使用してサービス リクエストを実行します。要求/app/api/rest?formatType=json&opName=userAPISubmitServiceRequest&opData={param0:"cat82",param1:"vdc82", param2:1,param3:-1,param4:1,param5:"vm provisioning"}それぞれの説明は次のとおりです。
{ "serviceResult":456, "serviceError":null, "serviceName":"InfraMgr", "opName":"userAPISubmitServiceRequest" }VM をプロビジョニングするためのサービス リクエスト ID は 456 です。 |
プロビジョニングされた VM が不要になった場合、ロールバック ワークフローを使用して、その VM に割り当てられたリソースの解放と再割り当てを実行できます。Write - Group Service Request ユーザ権限を持つシステム管理者またはエンド ユーザが、ワークフローのロールバックを実行できます。
ロールバック ワークフローには、userAPIRollbackWorkflow API 内で VM のプロビジョンに使用されたサービス リクエストの ID を渡すタスクを含める必要があります。進行中のサービス リクエストの ID は、Cisco UCS Director( )から入手できます。
他のユーザによってプロビジョニングされた VM をロールバックする場合、そのユーザから承認を得るためのロールバック ワークフロー承認が起動されます。ロールバック ワークフローは、承認の受信後に完了します。
要求
/app/api/rest?formatType=json&opName=userAPIRollbackWorkflow&opData={param0:456}
{ "serviceResult":458, "serviceError":null, "serviceName":"InfraMgr", "opName":"userAPIRollbackWorkflow" }userAPIGetServiceRequestWorkFlow API を使用して、以下のようにロールバック ワークフローのステータスを確認します。
/app/api/rest?formatType=json&opName=userAPIGetServiceRequestWorkFlow&opData={param0:458}ロールバック ワークフローの実行が正常に完了すると、stepId は [完了(Complete)] として表されます。VM に割り当てられているリソースが解放され、再割り当てできるようになります。
例外
ワークフローのロールバックに失敗した場合、userAPIRollbackWorkflow API は例外をスローします。
REMOTE_SERVICE_EXCEPTION: Cannot rollback work-flow for SR ID 332, when the work-flow execution is in progress
REMOTE_SERVICE_EXCEPTION: Cannot Rollback SR:332 as it is already rolled back.