VMware Cloud on AWS API Lab Manual

はじめに

このラボ演習では、どのようにプログラマブルな方法で VMware Cloud on AWS プラットフォームと連携することができるのかを見ていきます。vCenter インスタンスと同様に VMware Cloud on AWS と連携する手段として、どのように PowerShell を利用できるのかを確認していきます。そして、どのように VMware Cloud on AWS の REST API で連携できるのか、どのようにコンソールに統合された “Developer Center” と人気のある 3rd パーティー且つオープンソースの REST クライアントを駆使していくのか、について掘り下げていきます。このラボ演習のために、REST クライアントとして “Postman” を活用します。

PowerShell の活用

APIs1

  1. Start をクリックし、Windows PowerShell が表示されるまでスクロールダウンさせます
  2. PowerShell CLI ショートカットを右クリックし、Run as Administrator を選択します

    APIs3

VMware PowerCLI モジュールをインストールします

Install-Module VMware.PowerCLI

注意: NuGet provider のインストールを行うかを訊かれるので、デフォルトを選択するか、Y と入力し Enter を押下します。次に信頼されないリポジトリを信頼するかどうかを訊かれます。ここでは、デフォルトは 選択せず に、Y と入力し Enter を押下します。

APIs4

ここでは実行ポリシーを Remote Signed に設定します。

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Force

APIs5

次に、無効な証明書を無視するよう PowerCLI を構成する必要があります。

重要な手順:

Set-PowerCLIConfiguration -InvalidCertificateAction Ignore -Confirm:$false -WarningAction:SilentlyContinue

注意: コピー&ペーストを利用しない場合、”Ignore” の “i” が大文字であることを確認してください。

APIs6

VMware CLI のコマンドをインストールします。

Install-Module -name VMware.VMC -scope AllUsers -Force

APIs7

それでは簡単に VMware PowerCLI のコマンドを見てみましょう。

Get-VMCCommand -WarningAction:SilentlyContinue

APIs8

次に VMC コンソールからリフレッシュ トークンを取得してきます。Web ブラウザに戻るか、新しくブラウザを開き vmc.vmware.com にログインします。

もしログインしていないのであれば

  1. 新しいタブを開きます
  2. VMware Cloud on AWS のショートカットをクリックします
  3. Email アドレスを入力します
  4. Next をクリックします

    APIs9

  5. 名前/組織 ID のとなりのドロップダウンをクリックします
  6. マイアカウント をクリックします

    APIs10

    この組織にリンクされた ID のために新しいリフレッシュトークンを作成します

  7. API トークン タブをクリックします
  8. 新しい API トークンの作成 をクリックします

    APIs11

  9. トークンの名前を入力します
  10. 組織の所有者 のチェックボックスを選択します
  11. VMware Cloud on AWS のチェックボックスを選択します
  12. 生成 ボタンをクリックします

    APIs012

  13. クリップボードにリフレッシュトークンを保存さうるために コピー ボタンをクリックします

注意: このリフレッシュトークンは安全な所に保存してください。次のセクションで Postman で API を利用する際に利用します。

それでは VMC サーバーにアタッチしてみましょう。以下のコマンド入力し -refreshtoken パラメーターの後にリフレッシュトークンを付け加えます

connect-vmc -refreshtoken

APIs13

これで PowerShell を通じて VMC の組織に接続されました。どの組織にアクセスできるのかを以下のコマンドで確認できます

Get-VMCorg

組織の Display_Name と ID をメモします

APIs14

組織の Display_Name が分かったので、組織内の SDDC の情報を見ることができます

注意: # は受講者番号です

Get-VMCSDDC -Org VMC-WS#

APIs15

その他の実行できるクールなことというと、SDDC のデフォルトのクレデンシャルを確認できることです

Get-VMCSDDCDefaultCredential -org VMC-WS#

NOTE: # は受講者番号です

Developer Center からの REST API

このモジュールでは、VMware Cloud on AWS の REST API を使って、VMware Cloud on AWS の組織とデプロイされた SDDC の基本的な情報を取得します。これを行うために、VMware Cloud on AWS の Developer Center 機能を利用します。これは API を使うことに特化され組み込まれた機能です。SDDC の作成、ホストの追加、削除、さらには vCenter API の完全なセットへの接続と利用を可能にします。開始する前に、VMC 環境に戻りましょう

DeveloperCenter1

View デスクトップ上で Chrome ブラウザを起動します

DeveloperCenter2

まだログイン済みでなければ、VMware Cloud on AWS の組織にログインします

  1. VMware Cloud on AWS の中から、デベロッパー センターのメニューをクリックします

    DeveloperCenter3

    デベロッパー センターには、様々なお試しのための多くの素晴らしいリソースがあります。例えば、API 開発者の一人がアップロードしたコードサンプルを見てみましょう。この画面でスクロールしてみると、Postman (REST API 開発ツール) のサンプルコードを確認することができます

    また、Python、PowerCLI など様々なサンプルを見つけることができます。このコミュニティにサンプルコードを提供したい方は、https://code.vmware.com に行き、Sample Exchange をクリックしてください

  2. メニューの コードサンプル をクリックします
  3. “PowerCLI - VMC Example Script” の箱にある ダウンロード をクリックします

    DeveloperCenter4

  4. スクリプトをダウンロードした後、ブラウザ下部のドロップダウンメニューをクリックします
  5. フォルダーを表示 をクリックします
  6. PowerCLI-Example-Scripts-master.zip ファイルを Unzip します
  7. PowerCLI-Example-Scripts-master フォルダーを開きます
  8. Scripts フォルダーを開きます
  9. VMware_Cloud_on_AWS フォルダーを開きます
  10. VMC Example Script.ps1 スクリプトを右クリックします
  11. 編集をクリックします

    この操作は PowerShell ISE 環境を開きます。SDDC で利用できるコマンドの他に、前のモジュールで実行した PowerShell コマンドを見ることができます。それでは PowerShell ISE ウィンドウをクローズします

    DeveloperCenter6

    それでは、デベロッパーセンターに組み込まれた簡単な REST API コマンドを実行してみましょう。ブラウザに戻ります

  1. API エクスプローラー メニューをクリックします
  2. 受講者の SDDC が選択されていることを確認します
  3. Organization のとなりのドロップダウンの矢印をクリックします
  4. 一つ目の “GET” API のとなりのドロップダウンの矢印をクリックします
  5. 実行 をクリックします

    DeveloperCenter7

    何をしなかったでしょうか?このデータを取得するために一切認証を行いませんでした。その理由は、このコマンドを実行するための認証が行われたブラウザセッションを使っているからです。Postman や PowerCLI といった他のアプリケーションでこれらのコマンドを実行する場合には、コマンドを実行する前にリソースとセッショントークンを事前に取得する必要があります。

    ではレスポンスを見ていきましょう

  6. 組織のアルファベットと数字の識別子を確認できます
  7. 組織の ID注意 ID 番号をクォートなしでコピーします。この後のステップで利用します
  8. 組織の Display_Name
  9. 組織の Version

    DeveloperCenter8

    このステップでは、組織の情報を取得しました。

  10. SDDCs のとなりのドロップダウンの矢印をクリックします
  11. GET をクリックします
  12. 組織の ID は既に入力されています。これは顧客のフィードバックをベースとしたデベロッパーセンターにビルトインされた素晴らしい機能です。注意: もし組織の ID が自動的に入力されていない場合、組織 ID をペーストします
  13. 実行 をクリックします

    DeveloperCenter9

    ではレスポンスのボディを見ていきましょう

  14. SDDC の作成日
  15. SDDC の ID
  16. SDDC の状態

Postman

In this module, we will be exploring how to use Postman to execute REST API requests and build automation through collections. Postman is an API Explorer tool. As an example, you can create variables for use within the APIs, test the response, and use webhooks to integrate with collaboration platforms.

Postman1

Postman is very easy to install, so let’s get started.

  1. Open a new browser tab and go to https://www.getpostman.com
  2. Click on Download the App

    Postman2

  3. Select Postman for Windows (64-bit). Click Download. Double-click on the downloaded file, the install will execute without interaction.

    NOTE: For cleanup you can close all postman tabs in Chrome

    Postman3

  4. Click on the text: Skip Signing in and Take me straight to the app

    Postman4

  5. Uncheck Show this window on launch
  6. Close this window

    Postman5

    Go back to your browser window, if you do not have a tab opened for VMware Cloud on AWS, follow the below instructions

  7. Navigate to https://github.com/vmware/vsphere-automation-sdk-rest/archive/master.zip to download the vSphere Automation REST SDK.

    Our internal API development team has done a great job pre-creating SDKs for many of the popular languages in use today. For this module, we will be using the SDK for REST to show you how you can easily import and reuse some pre-built collections to create your own.

    Postman7

  1. This step intentionally left blank
  2. This step intentionally left blank
  3. Click on the download menu
  4. Click on Open

    Postman8

  5. Click on Extract
  6. Click on Extract all

    Postman9

    We will keep the default file path.

  7. Uncheck the box
  8. Click on Extract

    Close the file explorer window

    Postman10

    Now that we have Postman installed and our REST samples on our local system, lets import the VMC collection and use some the requests to build our own collection.

  9. Click on Import
  10. Click on Choose Files

    Postman11

    To import the VMC collection json file we downloaded earlier.

  1. Browse to the directory we extracted the zip file to earlier. That directory should be C:\downloads\vsphere-automation-sdk-rest-master\vsphere-automation-sdk-rest-master\samples\postman
  2. Click VMware Cloud on AWS APIs.postman_collection.json
  3. Click Open

    Postman12

    We now need to get our refresh token for our Org in VMC. Go back to your VMware Cloud on AWS tab in your browser

  4. Click on the drop down next to your Name/Org ID
  5. Click on My Account

    We will now create a new Refresh Token for the ID linked to this Org.

    NOTE: If you have already generated a token, use the same token that was generated. You can also regenerate a new token if needed.

    Postman13

  6. Click on API Tokens tab.
  7. Click Generate a New API Token

    APIs011

  8. Give the token a name.
  9. Select checkbox by Organization Owner.
  10. Select checkbox by VMware Cloud on AWS.
  11. Click Generate button.

    APIs012

  12. Click on Copy button to save refresh token to clipboard.

    Postman16

    Return to the Postman app. We now need to setup a Postman environment for use with VMC. An environment is where we will be creating and storing our variables. These variables can be local or global, depending on your use within Postman. In this module, we will only be using local variables.

  13. Click on New
  14. Click on Environment

    Postman17

  15. Name the environment VMC
  16. In the Key column type in refresh_token
  17. In the Value column use CTRL-V to paste your actual refresh token you copied in a previous step.
  18. Click on Add
  19. Close the window

    Postman18

    Now set this as our default environment.

    NOTE: If you don’t set the default environment to VMC, then the variables that get created will not be accessible.

  1. Click on the drop down arrow
  2. Select VMC

    Postman19

    Now we will start to build our own collection by using some request that came in the SDK we imported earlier.

  3. Click on Collections
  4. Click on - Authentication and Login
  5. See how this request is our refresh token variable we defined in an earlier step.

    NOTE: If the environment is not set to VMC, this will request will fail because the refresh_token variable is not defined.

  6. Click on Send
  7. You will now see the access token that was generated with the refresh token. This is the body or payload of the response to our request.

    Postman20

  8. Click on the Eye icon

    You will see that we have stored your access token into a variable so we can use it for futurecalls. How did we do that? We ran a “test” on the response body. You will see how in the next step.

    Postman21

  9. Click on Tests

    The access_token variable was set by running some java script code against the response. We are also using the Postman setEnvironmentVariable function to create it.

    Postman22

    Lets save this request to our own collection so we can use it later.

  10. Click on the drop down arrow
  11. Click on Save As

    Postman23

  12. Change the Request name to Authorize
  13. Change the Request description to Get Access Token
  14. Click on Create Collection
  15. Type Workshop and click the check box

    Postman24

  1. Select the Workshop folder
  2. Click on Save to Workshop

    Postman25

    A new window will pop open indicating that you created a new collection. We will not do anything here at this time.

  3. Close this window

    Postman26

    Let’s request some details from our Org so we can send them to Slack.

  4. Click on Orgs and List Orgs
  5. Click on Headers
  6. Click Send
  7. You see here how we are using the access_token variable for the csp-auth-token. This will authorize our request. NOTE: This access token is only good for 30 minutes. If you run this request and get a response of 400 unauthorized, go back and run the authorize request.
  8. Look through the response body for your Org’s display_name

    Postman27

    Let’s save this request to our own collection so we can use it later.

  9. Click on the drop down arrow
  10. Click on Save As

    Postman28

  11. Change the Request name to Org list
  12. Change the Request description to Get a list of your Orgs
  13. Be sure Workshop is selected under Select a collection or folder to save to:
  14. Click on Save to Workshop

    Postman29

    We need to replace the Test code that came with the SDK so we can create variable we want to use when send our message to Slack.

  15. Click on Tests Copy and paste the below code into the Tests section. NOTE: You may have to press CTRL-V to paste into the text box.
  16. Click Send

    var jsonData = JSON.parse(responseBody);
    
    if (responseCode.code === 200) {
    for (i = 0; i < jsonData.length; i++) {
      pm.environment.set("name", jsonData[i].display_name);
      pm.environment.set("ID", jsonData[i].id);
      pm.environment.set("version", jsonData[i].version);
      pm.environment.set("state", jsonData[i].project_state);
       }
     }
    

    Postman30

    We can verify if the variables have been created and assigned values.

  1. Click on the eye icon
  2. Scroll down to see if the new variables were created. Once verified click on the “eye” icon again to close the window

    Postman31

    Lets save the changes we made to this request.

  3. Click on Save

    Postman32

    Now that we have details of our Org lets send them to slack inn a message.

    To post to slack a link needs to be generated for the slack channel that we want to post to. This has already been done for you and is listed below. One of the instructors will have this slack channel displayed on the screens. So you can see the results.

    Slack channel URL:

    https://hooks.slack.com/services/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
    

    Now we need to setup the request:

  4. Click on the + sign for a new request
  5. Change the request type to POST
  6. Cut and paste the above slack channel URL to the address box
  7. Select Body
  8. Change the format type to raw
  9. Type the below code, or cut and paste it into the Body section. NOTE: You may have to press CTRL-V to past into the text box.

    {
      "text" : "Your Org ID is: {{ID}}\nYour Org version is: {{version}}\nAnd your Org state is: {{state}}",
      "username" : "{{name}}"
    }
    
  1. Click Send

    Postman33

    Lets save this request to our own collection so we can use it later.

  2. Click on the drop down arrow
  3. Click on Save As

    Postman34

  4. Change the Request name to Post to Slack
  5. Change the Request description to Post some Org details to slack Be sure Workshop is selected under Select a collection or folder to save to:
  6. Click on Save to Workshop

    Check and see if your request posted the Name, ID, Version, and Status of your Org.

    Postman35

    The last thing to show you with Postman is the way that you can run a collection to automate a series of tasks. What we have been doing in this module is building a collection. As you see in the screen shot there are 3 tasks in the Workshop collection.

  7. Click on the Arrow in the Workshop window
  8. Click on Run

    Postman36

  9. Click on Run Workshop
  10. Be sure the Environment is set to VMC

    Postman37

    If all your work was saved and ran individually, they should run here as well.

  11. Check out the status of each request.

If you have all “200 OK” then you will see another post in slack for your workshop Org.

Please add comments below if you would like to give feedback on this lab.

Updated:

Leave a Comment