日本語は機械翻訳による参考訳です。内容に矛盾や不一致があった場合には、英語の内容が優先されます。

Cloud Insights API の略

寄稿者 netapp-alavoie dgracenetapp このページの PDF をダウンロード

Cloud Insights API を使用すると、ネットアップのお客様と独立系ソフトウェアベンダー( ISV )は、 CMDB やその他のチケット処理システムなどの他のアプリケーションと Cloud Insights を統合できます。

Cloud Insights API は、現在のエディションに基づいて提供されています。

API カテゴリ 基本 標準 Premium サービス

Acquisition Unit の略

データ収集

アラート

資産

データの取り込み

API アクセスの要件

  • API アクセストークンモデルを使用してアクセスが許可されます。

  • API トークン管理は、管理者ロールを持つ Cloud Insights ユーザが実行します。

API ドキュメント( Swagger )

最新の API 情報は、 Cloud Insights にログインし、 * Admin > API アクセス * に移動することで確認できます。[API Documentation*] リンクをクリックします。

API のドキュメント

API ドキュメントは Swagger ベースです。 API の簡単な概要情報と使用方法を提供しており、環境内で試すことができます。

API Swagger の例

API アクセストークン

Cloud Insights API を使用する前に、 1 つ以上の * API アクセストークン * を作成する必要があります。アクセストークンは、指定された API カテゴリに対して使用され、読み取り権限と書き込み権限を付与できます。各アクセストークンの有効期限を設定することもできます。指定したカテゴリのすべての API がアクセストークンに対して有効です。各トークンはユーザ名またはパスワードを無効にします。

アクセストークンを作成するには:

  • [Admin] > [API Access] をクリックします

  • [*+API アクセストークン *] をクリックします

    • トークン名を入力します

    • API カテゴリを選択します

    • この API アクセスに付与する権限を指定します

    • トークン有効期限を指定します

注記 トークンは、クリップボードにコピーして作成プロセス中に保存する場合にのみ使用できます。トークンは作成後に取得できないため、トークンをコピーして安全な場所に保存することを強くお勧めします。トークン作成画面を閉じる前に、 [API アクセストークンのコピー *] ボタンをクリックするよう求められます。

トークンを無効化、有効化、および取り消しできます。無効になっているトークンを有効にできます。

トークンを使用すると、お客様の観点から API への汎用アクセスが許可され、独自のテナントの範囲内で API へのアクセスが管理されます。お客様の管理者は、 Cloud Insights のバックエンド担当者に直接関与せずに、これらのキーを付与したり取り消したりできます。

アプリケーションは、ユーザがアクセスの認証と許可に成功した後、ターゲット API を呼び出すときにアクセストークンをクレデンシャルとして渡します。渡されたトークンは、 API にアクセスするためのトークンのベアラーが許可されていることを API に通知し、許可中に許可されたスコープによって指定された特定のアクションを実行します。

アクセストークンが渡される HTTP ヘッダーは * X-CloudInsights - apiKey : * です。

たとえば、次のようにしてストレージアセットを取得します。

 curl https://<tenant_host_name>/rest/v1/assets/storages -H 'X-CloudInsights-ApiKey: <API_Access_Token>'
_<API_Access_Token> _ は、 API アクセスキーの作成時に保存したトークンです。

API カテゴリ

Cloud Insights API はカテゴリベースであり、現在、次のカテゴリで構成されています。

  • アセットのカテゴリには、アセット、クエリ、および検索用の API が含まれています。

    • アセット:最上位のオブジェクトを列挙し、特定のオブジェクトまたはオブジェクト階層を取得します。

    • クエリ: Cloud Insights クエリを取得および管理します。

    • インポート:アノテーションまたはアプリケーションをインポートしてオブジェクトに割り当てます

    • 検索:オブジェクトの一意の ID またはフルネームを知らずに、特定のオブジェクトを検索します。

  • データ収集カテゴリは、データコレクタを取得および管理するために使用します。

  • データ取り込みカテゴリは、 Telegraf エージェントなどの取り込みデータとカスタムメトリックを取得および管理するために使用されます

その他のカテゴリや API は、時間の経過とともに利用できるようになる場合があります。最新の API 情報は、で確認できます "API Swagger のドキュメント"

ユーザがアクセスできる API カテゴリは、によっても異なります "ユーザロール" 各 Cloud Insights 機能セット( Monitoring 、 Cloud Secure 、 Reporting )に含まれています。

在庫移動

このセクションでは、 Cloud Insights オブジェクトの階層をトラバースする方法について説明します。

トップレベルオブジェクト

個々のオブジェクトは、一意の URL ( JSON では「 self 」)によって要求に示され、オブジェクトタイプと内部 ID を知る必要があります一部のトップレベルオブジェクト(ホスト、ストレージなど)については、 REST API を使用して完全なコレクションにアクセスできます。

API URL の一般的な形式は次のとおりです。

 https://<tenant>/rest/v1/<category>/<object>
たとえば、 _mysite.c01.cloudinsights.netapp.com_ という名前のテナントからすべてのストレージを取得する場合、要求の URL は次のようになります。
https://mysite.c01.cloudinsights.netapp.com/rest/v1/assets/storages

子および関連オブジェクト

ストレージなどの最上位のオブジェクトは、他の子や関連オブジェクトへのトラバースに使用できます。たとえば、特定のストレージのすべてのディスクを取得するには、ストレージの「 self 」 URL を「 /disks 」に連結します。次に例を示します。

https://<tenant>/rest/v1/assets/storages/4537/disks

展開します

多くの API コマンドでは、関連オブジェクトのオブジェクトや URL に関する追加情報を提供する * expand * パラメータがサポートされています。

共通の展開パラメータの 1 つは _expands_です応答には、オブジェクトに対して使用可能なすべての特定の展開のリストが含まれています。

たとえば、次のように要求したとします。

 https://<tenant>/rest/v1/assets/storages/2782?expand=_expands
API は、オブジェクトに対して使用可能なすべての拡張を次のように返します。

例を展開します

各展開には、データ、 URL 、またはその両方が含まれます。expand パラメータでは、次のような複数の属性とネストされた属性がサポートされます。

 https://<tenant>/rest/v1/assets/storages/2782?expand=performance,storageResources.storage
Expand を使用すると、関連するデータを 1 回の応答で大量に取り込むことができます。ネットアップでは、一度に大量の情報を要求しないことを推奨しています。これにより、原因のパフォーマンスが低下する可能性があります。

これを防止するために、トップレベルのコレクションに対する要求は展開できません。たとえば、すべてのストレージオブジェクトの拡張データを一度に要求することはできません。クライアントは、オブジェクトのリストを取得し、特定のオブジェクトを選択して拡張する必要があります。

パフォーマンスデータ

パフォーマンスデータは、さまざまなデバイスにわたって個別のサンプルとして収集されます。Cloud Insights は、 1 時間ごと(デフォルト)にパフォーマンスサンプルをまとめたものです。

この API を使用すると、サンプルと集計データの両方にアクセスできます。パフォーマンスデータが格納されたオブジェクトの場合、パフォーマンスの概要は expand = performion.パフォーマンス履歴の時系列は、 Nested_expand= perform中 .history_ で確認できます。

パフォーマンスデータオブジェクトには次のようなものがあります。

  • ストレージパフォーマンス

  • StoragePoolPerformance の各ノードでパフォーマンスが

  • PortPerformance の 2 つのグループ

  • ディスクパフォーマンス

パフォーマンス指標には概要とカテゴリがあり、パフォーマンス概要のコレクションが含まれています。たとえば、 Latency 、 Traffic 、 Rate などです。

パフォーマンスサマリーには、 1 つのパフォーマンスカウンタから特定の期間( 1 時間、 24 時間、 3 日間など)にわたって計算された概要、ユニット、サンプル開始時間、サンプル終了時間、および要約された値(現在、最小、最大、平均など)のコレクションが含まれます。

API パフォーマンスの例

結果の Performance Data ディクショナリには、次のキーがあります。

  • 「 self 」は、オブジェクトの一意の URL です

  • 「 history 」は、タイムスタンプとカウンタ値のマップのペアのリストです

  • 他のすべてのディクショナリキー(「 diskThroughput 」など)は、パフォーマンスメトリックの名前です。

パフォーマンスデータのオブジェクトタイプごとに、一意のパフォーマンス指標のセットがあります。たとえば、仮想マシンのパフォーマンスオブジェクトは、パフォーマンスメトリックとして「 diskThroughput 」をサポートします。サポートされている各パフォーマンスメトリックは、メトリックディクショナリに示されている特定の「パフォーマンスカテゴリ」です。Cloud Insights では、本ドキュメントで後述するパフォーマンス指標のカテゴリを複数サポートしています。各パフォーマンスメトリックディクショナリには、このパフォーマンスメトリックの判読可能な概要である「概要」フィールドと、パフォーマンスサマリーカウンタエントリのセットも含まれます。

Performance Summary カウンタは、パフォーマンスカウンタの要約です。これは、カウンタの一般的な集計値であり、最新の測定値、要約データの時間範囲、カウンタの単位タイプ、データのしきい値なども表示します。しきい値のみオプションで、残りの属性は必須です。

パフォーマンス要約は、次のタイプのカウンタで使用できます。

  • Read –読み取り処理の概要

  • Write –書き込み処理の概要です

  • Total –すべての処理の概要。読み取りと書き込みの単純な合計よりも高くなる場合があり、それ以外の処理も含まれる場合があります。

  • Total Max –すべての処理の概要。指定した期間内の最大合計値です。

オブジェクトのパフォーマンス指標

API は、環境内のオブジェクトについて、次のような詳細な指標を返すことができます。

  • IOPS ( 1 秒あたりの入出力要求の数)、レイテンシ、スループットなどのストレージパフォーマンス指標。

  • スイッチのパフォーマンス指標:トラフィック利用率、 BB クレジットゼロデータ、ポートエラーなど。

を参照してください "API Swagger のドキュメント" 各オブジェクトタイプの指標に関する情報が表示されます。

パフォーマンス履歴データ

履歴データは、タイムスタンプとカウンタマップのペアのリストとしてパフォーマンスデータに表示されます。

履歴カウンタの名前は、パフォーマンス指標オブジェクトの名前に基づいて決まります。たとえば、仮想マシンのパフォーマンスオブジェクトは「 diskThroughput 」をサポートしているため、履歴マップには「 diskThroughput 」、「 diskThroughput 」、「 diskThroughput 」、「 diskThroughput 」、「 diskThroughput total 」という名前のキーが含まれます。

注記 timestamp は UNIX の時間形式です。

ディスクのパフォーマンスデータの JSON の例を次に示します。

ディスクパフォーマンス JSON

容量属性を持つオブジェクト

容量の属性を持つオブジェクトは、基本的なデータ型と CapacityItem を使用して表現します。

CapacityItem

CapacityItem は、容量の単一の論理ユニットです。親オブジェクトで定義された単位には「値」と「高しきい値」があります。また、容量値の構成方法を説明するオプションの内訳マップもサポートしています。たとえば、 100TB の StoragePool の総容量は、 1 、 000 の CapacityItem になります。この内訳では、「データ」に 60 TB 、「スナップショット」に 40 TB が割り当てられています。

「 highThreshold 」は、対応するメトリックのシステム定義のしきい値を表します。このしきい値を使用すると、クライアントは、許容範囲外の設定された値に関するアラートや視覚的なキューを生成できます。

次に、複数の容量カウンタがある StoragePools の容量を示します。

ストレージプール容量の例

[ 検索( Search ) ] を使用してオブジェクトを検索する

検索 API は、システムへのシンプルなエントリポイントです。API に対する唯一の入力パラメータは自由形式の文字列であり、結果の JSON には分類された結果のリストが含まれています。カテゴリは、ストレージ、ホスト、データストアなど、インベントリのアセットタイプによって異なります。各カテゴリには、検索条件に一致するカテゴリタイプのオブジェクトのリストが含まれます。

Cloud Insights は拡張可能な(オープンな)解決策で、サードパーティのオーケストレーションシステム、ビジネス管理システム、変更管理システム、チケット処理システムとの統合や、カスタム CMDB の統合を可能にします。

Cloud Insight の RESTful API は、データのシンプルかつ効果的な移動を可能にし、ユーザがデータにシームレスにアクセスできるようにする統合の主要なポイントです。