Turbonomic REST API の使い方

API を使用して結果を確認する最も簡単な方法は、Swagger UI で呼び出しを試行することです。 Swagger UI を使用するには、以下にナビゲートします。

https://<Your_Turbonomic_URL>/apidoc

Swagger UI を使用してさまざまなエンドポイントにナビゲートし、それらのメソッドを試すことができます。例えば、「ユーザー」エンドポイントにナビゲートすると、 Turbonomic インストール済み環境に指定されているすべてのユーザーのリストを取得できます。詳しくは、 Turbonomic REST API Swagger の資料を参照してください。

最終的には、API を使用してデータを取得したり、アクションを実行したり、 Turbonomic を他のプロセスと統合したりするスクリプトを実装する必要があります。 API を操作する際には、以下について知っておく必要があります。

認証
URI 構造
応答フォーマット
Turbonomic API における時刻

認証

API を使用するには、 Turbonomic インスタンス上に有効なユーザー・アカウントを持っている必要があります。また、アカウントは異なる役割を持つことができることにも注意してください。 API は、ユーザー・ロールに有効なコマンドのみを実行します。例えば、 Turbonomic 推奨アクションを実行するには、アカウントに administrator、 deployer、または automatorのいずれかの役割が必要です。

API 呼び出しを行うには、認証トークンを要求し、それを Turbonomic API の呼び出しごとに渡します。トークン要求は、認証用の Cookie を返します。このトークンを使用する一般的な方法は、Cookie をローカルに保管し、API 呼び出しで渡すことです。

例: curl -s -k -c /tmp/cookies -H 'accept: application/json' 'https://localhost/api/v3/login?hateoas=true' -d 'username={your_username}&password={your_password}'

次に、各リクエストは、ログインリクエストによって配信されたセッションクッキーを使用するために、 -b cookie-filename パラメータを使用する必要があります。

もう 1 つの方法は、認証ヘッダーを取得し、認証 Cookie を解析することです。その後、Cookie を含む API 要求ごとにヘッダーを作成できます。例えば、 tokenという名前の変数に値を保管するとします。次のように使用できます。

headers = {'cookie': token}
r = requests.get('https://10.10.123.456/api/v3/targets/specs', headers=headers, verify=False, stream=True)

注: 詳細な説明については、API Cookbook の「 Authentication Recipe 」を参照してください。

URI構造

Turbonomic REST API を使用するには、クライアントは特定の REST リソースに対して HTTP リクエストを送信します。 Turbonomic REST APIは、標準 HTTPをサポートしています

GET

エンティティーまたはデータ・オブジェクトのリストを取得し、個々の項目を取得します。
POST

Turbonomic 環境で新規オブジェクトを作成するか、特定の照会に対してフィルターを指定します。
PUT

既存のエンティティーまたはオブジェクトを段階的に変更します。
DELETE

エンティティーまたはオブジェクトを削除します。

Turbonomic REST API リソースの基本 URI 構造は、以下のとおりです。


        https://<Your_Turbonomic_URL>/api/<API_version>/<resource_name>

例えば、インストール済み環境内のユーザーをリストするには、以下のようにします。

https://111.222.33.44/api/v3/users

応答形式

Turbonomic REST API は、JSON オブジェクトとしてデータを返します。 Turbonomic は、これらのオブジェクトをデータ転送オブジェクトまたは DTO と呼びます。 DTO は、要求したデータを記述するキーと値のペアの配列、または POST または PUTを実行した結果であるデータの配列です。例えば、 Turbonomicのインストール用に定義されたユーザーを GET すると、API は次のような DTO を返します。


[
  {
  "links": [
    {
      "rel": "self",
      "href": "https://10.10.10.10/api/v3/users/_4T_7kwY-Ed-WUKbEYSVIDw"
    }
  ],
  "uuid": "_4T_7kwY-Ed-WUKbEYSVIDw",
  "displayName": "Administrator User",
  "username": "administrator",
  "roleUuid": "_4UAioQY-Ed-WUKbEYSVIDw",
  "roleName": "administrator",
  "loginProvider": "Local",
  "type": "DedicatedCustomer",
  "showSharedUserSC": false
  }
]

この場合、DTO は 1 つのオブジェクトの配列です。言い換えると、 Turbonomicのこのインストールに定義されているユーザー・アカウントは 1 つだけです。ユーザーオブジェクトは、このユーザーアカウントURL links 配列で始まります。次に、指定されたユーザー・アカウントを記述するプロパティーについて説明します。

ほとんどの場合、 PUT または POSTを実行するために、DTO を介してオブジェクトを作成するためのパラメーターを渡すことに注意してください。これらの DTO は、関連する応答 DTO と似ていますが、同一ではありません。この例のユーザー・アカウントの場合、応答 DTO にはユーザー・アカウント・パスワードは含まれませんが、アカウントを作成するための DTO にはパスワードが含まれている必要があります。

Swagger UI でさまざまな REST メソッドを試すことで、標準的な応答 DTO を確認できます。

Turbonomic API における時刻

Turbonomic REST API には、情報を作成またはフィルタリングするために開始時刻または終了時刻 (あるいはその両方) を必要とする要求が含まれています。時刻は、以下の 3 つの異なる形式で入力できます。

ISO 8601 日付と時刻の形式

YYYY-MM-DDTHH:MM:SS 例えば、 2018-10-07T12:38:17 のようになります。
エポック時間

エポック時間は、UTC 1970 年 1 月 1 日の午前 0 時からの経過秒数として表されます。例えば、 1514764800 は 2018 年 1 月 1 日 12:00:00 AM UTC に対応します。
相対時間
相対時間は、呼び出しが実行される相対時間として表されます。例えば、開始時刻が -1w で終了時刻が -1d の場合、呼び出しが実行される前の週から呼び出しが実行される前の日までのエントリーを結果に含める必要があることを示します。相対単位には大/小文字の区別があります。 Turbonomic は、以下の相対単位をサポートします。
- m -分
- h -時間
- d -日
- w -週
- M -月
- y -年

Turbonomic API でのページ編集

一部の API 呼び出しは、非常に大きなデータ・セットを返します。 Turbonomic では、常にページ編集機能を使用することを推奨しています。これは、 Turbonomicによって管理される大規模な環境の場合に特に重要です。個々の要求に対してスコープとフィルターを使用することで、データを事前にフィルターに掛けることができます。 limit パラメーターと x-next-cursor パラメーターを使用すると、管理可能なチャンクでデータを返すことができます。

例:

https://10.10.10.10/api/v3/markets/214075923753936/entities/stats?limit=5&ascending=true

前の要求は、特定の市場のすべてのエンティティーの統計を取得することです。 limit=5 は、返されるデータの各ページに 5 つの結果があることを示します。

返されるデータのヘッダーには、 x-next-cursor: 5が含まれるようになります。結果の次のページを取得するには、次の要求でカーソルを使用します。

https://10.10.10.10/api/v3/markets/214075923753936/entities/stats?cursor=5&limit=5&ascending=true

最終ページに達すると、 x-next-cursor は空になります。

注：カーソルは文字列であり、ユーザーが解釈してはならない。異なるAPIエンドポイントは、異なる文字列カーソルフォーマットを持つかもしれない。特定のエンドポイントのカーソルのフォーマットは、時間の経過とともに変化するかもしれない。これは、結果の並べ替えやフィルタリングにおいて一定の効率を得るために必要なことである。

要求に orderBy, limit, パラメーターまたは cursor パラメーターが指定されている場合、これらのパラメーターのいずれかを使用すると、ページ編集された結果が返されます。