利用報告 エンドポイント

利用レポート・エンドポイントは、 AWS EC2 インスタンスの利用パターンを分析するために使用される。 Utilization Analyticsは、 AWS Cloudwatchのデータを使用し、平均CPU使用率（パーセント）、帯域幅、ディスクI/Oなどのインスタンスレベルの詳細を表示します。 利用状況分析は、全体的な弾力性や、インスタンスのサイズ変更が必要かどうか、またはインスタンスを停止する必要があるかどうかを可視化するのに最適です。

Utilization Analyticsで利用可能なコスト・メトリクスは、 Cloudability、オンデマンド・レートを使用して計算され、請求書のコンピュート部分のみをカバーします（つまり、請求可能なインスタンス時間であり、帯域幅、ストレージなどは含まれません）。 そのため、財務報告ではなく、傾向分析にのみ使用されるべきである。 なお、この指標は「コスト（推定）」と呼ばれる。

Utilization Analyticsが利用率データにアクセスするためには、各メンバー・アカウントに適切なIAM権限を付与する高度なクレデンシャルを設定する必要がある。

柔軟なフィルタリング、ソート、メジャー（ディメンションとメトリクス）の選択が可能で、特定のレポートニーズに合わせて結果を作成することができます。 推奨ガイドラインとして、APIコールに追加できるディメンジョンは最大15個、メトリクスは最大10個です。 デフォルトでは、結果はJSONで返される。 CSV形式で結果を得るには、Acceptヘッダーにtext/csvを設定してください。 後述するように、結果が10,000行を超えるとページネーションが実行されることに注意。 レポートの呼び出しの例は、この文書の一番下に記載されています。

利用報告終了点

• /reporting/reports/utilは 現在の利用報告書をリストアップする
• 利用レポートを実行するための /reporting/util/run
• /reporting/util/measures 利用可能な利用報告尺度をリストアップする
• /reporting/util/filters : フィルタで使用可能な比較演算子のリスト
• /reporting/util/enqueue ユーティリティレポートをキューに登録します
• /reporting/reports/:id/stateは、キューに入れられたレポートの状態をチェックする
• /reporting/reports/:id/resultsは、キューに入れられた終了レポートを取得する

利用報告オブジェクト

• results (array) - 利用行オブジェクトのリストで、各行は報告されたディメンジョンとメトリクスで構成されます
• meta (object) - 実行されたレポートに関するメタ情報を含むオブジェクト
  • dates (object) - レポートの日付範囲を示す開始日と終了日の文字列
  • filters (array) - 詳細情報を含むレポートに適用されるフィルタのリスト
  • metrics (array) - 詳細情報を含むレポートで返されるメトリクスのリスト
  • dimensions (array) - 詳細情報を含むレポートで返される次元のリスト
  • aggregates (array) - レポート用の詳細情報を持つ集約されたメトリクスのリスト
  • offset (数値) - 結果を開始する位置。 デフォルトは0です
  • limit (number) - 返される利用行の最大数
  • total_results (数値) - 実行されたレポートで返された利用率の合計行数

利用報告オブジェクトの例（レビュー例）

{
  "results": [
    {
      "instance_identifier": "i-1237aa0e1587577f5",
      "max_cpu_utilization": "0.91925"
    },
    {
      "instance_identifier": "i-0007aa0e1587572c7",
      "max_cpu_utilization": "0.179183"
    }
  ],
  "meta": {
    "dates": {
      "start": "2022-08-30T00:00:00Z",
      "end": "2022-08-30T00:00:00Z"
    },
    "filters": [],
    "metrics": [
      {
        "name": "max_cpu_utilization",
        "label": "CPU Utilization (Max)",
        "description": "The maximum percentage of CPU Utilization...
        "data_type": "percentage",
        "type": "metric",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 12,
          "Key": "processing",
          "Name": "Processing"
        }
      }
    ],
    "dimensions": [
      {
        "name": "instance_identifier",
        "label": "Instance ID",
        "description": "The ID associated with a particular AWS instance.",
        "data_type": "string",
        "type": "dimension",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 1,
          "Key": "common",
          "Name": "Common"
        }
      }
    ],
    "aggregates": [
      {
        "name": "max_cpu_utilization",
        "label": "CPU Utilization (Max)",
        "description": "The maximum percentage of CPU Utilization...",
        "data_type": "percentage",
        "type": "metric",
        "value": "0.91925"
      }
    ]
  },
  "offset": 0,
  "limit": 2,
  "total_results": 2
}

現在の利用レポート一覧

ユーザーまたは組織が所有または共有している利用レポートのリストを取得します。

curl 'https://api.cloudability.com/v3/reporting/reports/util' -u '[auth_token]:'

回答例

[
 {
  "id": 1,
  "author": {
  "id": 12345,
  "safe_name": "Test User"
  },
  "category": "Utilization",
  "custom": true,
  "description": "The number of instances running during each hour of the day over the last 7 days.",
  "dimensions": [
  {
  "name": "date",
  "label": "Date",
  "description": "The calendar date (e.g. YYYY-MM-DD).",
  "data_type": "date",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   },
  {
  "name": "hour",
  "label": "Hour",
  "description": "The numeric hour of the day (e.g. 1pm => 13).",
  "data_type": "integer",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   }
  ],
 "end_date": "23:59:59",
 "filters": [
 {
  "comparator": "==",
  "measure": {
  "name": "date",
  "label": "Date",
  "description": "The calendar date (e.g. YYYY-MM-DD).",
  "data_type": "date",
  "type": "dimension",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 2,
  "key": "time",
  "name": "Time"
  }
   },
  "value": "2019-06-24"
  }
   ],
  "metrics": [
 {
  "name": "running_instances",
  "label": "Unique Instance Count",
  "description": "The total number of unique instances in a running state during a given time period.",
  "data_type": "integer",
  "type": "metric",
  "group": {
  "id": 9,
  "key": "compute",
  "name": "Compute"
  },
  "sub_group": {
  "id": 8,
  "key": "usage",
  "name": "Usage"
  }
   }
    ],
  "order": "asc",
  "owned_by_user": false,
  "shared_with_organization": false,
  "permission": {
  "actions": [
  "read"
  ]
   },
 "report_dimension_links": [],
 "secondary_end_date": null,
 "secondary_start_date": null,
 "shared": true,
 "shares": [],
 "sort_by": "date",
 "star": false,
 "start_date": "7 days ago at 00:00:00",
 "subscriptions": [],
 "title": "Elasticity - Running Instances per Hour"
  },
    ]

利用可能な措置のリスト取得

サーバによって認識されたメジャーのリストを取得します。 Measures には、レポートで使用できるディメンジョンとメトリクスの両方が含まれます。 メジャー・エンドポイントで GET を実行するだけです。

curl ‘https://api.cloudability.com/v3/reporting/util/measures’ -u ‘[auth_token]:’

回答例

[
  {
    "name": "avg_cpu_utilization",
    "label": "CPU Utilization (Avg)",
    "description": "The average percentage of CPU Utilization...",
    "type": "metric",
    "group": {
      "id": 9,
      "key": "compute",
      "name": "Compute"
    },
    "sub_group": {
      "id": 12,
      "key": "processing",
      "name": "Processing"
    }
  },
  {
    "name": "utilization_hours",
    "label": "Utilization Hours",
    "description": "The total number of usage hours on an instance ...",
    "data_type": "integer",
    "type": "metric",
    "group": {
      "id": 9,
      "key": "compute",
      "name": "Compute"
    },
    "sub_group": {
      "id": 8,
      "key": "usage",
      "name": "Usage"
    }
  },
]

利用可能なフィルタ演算子のリストの取得

データを要求するために認識されたフィルター演算子のリストを取得する

curl ‘https://api.cloudability.com/v3/reporting/util/filters’ -u ‘[auth_token]:’

回答例

[
  "<=",   # less than or equals
  "[]=",  # in*
  ">="    # greater than or equals
  "<",    # less than
  "=@",   # contains
  "^=",   # matches
  "===",  # strictly equals*
  "==",   # equals
  "!=@",  # does not contain
  "!=",   # not equals
  "!==",  # strictly not equals*
  ">",    # greater than
  "!^=",  # does not match
  "!$=",  #does not end with
  "[]!=", # not in*
  "$=",   #end with
]	

* これらの演算子はAPI経由でのみ利用可能であることに注意してください

利用レポートを実行する

リクエストパラメーター

注： v3 コスト報告エンドポイントがサポートする相対的/動的な日付文字列：

ページネーションの処理

APIパフォーマンスをサポートするため、返されたレポートの行数が10,000を超えるとページネーションが実装されます。 これは通常、ユーザが resource_identifier のようなカーディナリティの高い複数のディメンジョンをレポートに追加した場合に発生します。 total_resultsの値が10,000であり、ページネーションオブジェクトが存在することは、ページネーションが行われたことを示している。

ページネーションオブジェクトの例：

"pagination": {
  "next": "38bc18d0",
  "previous": "1d93c71e"

レポートのページ間を前後に移動するには、 URL の末尾にトークン・クエリ・パラメータを追加し、該当するトークン値を指定します（例： token=38bc18d0 ）。

注 ：リクエストパラメーターに limit=0 を設定することで、自動ページ送りを64,000行まで増やすことができます

典型的な利用報告書 - 長期的な利用傾向

curl ‘https://api.cloudability.com/v3/reporting/util/run?start_date=2022-01-01&end_date=2022-06-30&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’"

回答例（結果の一部を示す）

{
  "results": [
    {
      "avg_cpu_utilization": "0.84463",
      "estimated_cost": "393.12",
      "instance_identifier": "i-0a70f28b01f652f14",
      "instance_name": "common-operations-ondemand-r5-large-green-Node",
      "instance_size": "r5.large",
      "total_bandwidth": "2019199735862",
      "utilization_hours": "24",
      "vendor_account_name": "My Account Name"
    },
    {
      "avg_cpu_utilization": "0.830585",
      "estimated_cost": "1071.2",
      "instance_identifier": "i-0278b62c3679c7286",
      "instance_name": "production-operations-spot-16cpu-64gb-green-Node",
      "instance_size": "m5ad.4xlarge",
      "total_bandwidth": "864959230667",
      "utilization_hours": "9",
      "vendor_account_name": "My Account Name"
    }
  ],
  "meta": {
    "dates": {
      "start": "2022-08-30T00:00:00Z",
      "end": "2022-08-30T00:00:00Z"
    },
    "filters": [],
    "metrics": [
      {
        "name": "avg_cpu_utilization",
        "label": "CPU Utilization (Avg)",
        "description": "The average percentage of CPU Utilization...",
        "data_type": "percentage",
        "type": "metric",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 12,
          "Key": "processing",
          "Name": "Processing"
        }
      }
    ],
    "dimensions": [
      {
        "name": "instance_identifier",
        "label": "Instance ID",
        "description": "The ID associated with a particular AWS instance.",
        "data_type": "string",
        "type": "dimension",
        "group": {
          "ID": 9,
          "Key": "compute",
          "Name": "Compute"
        },
        "sub_group": {
          "ID": 1,
          "Key": "common",
          "Name": "Common"
        }
      }
    ],
    "aggregates": [
      {
        "name": "avg_cpu_utilization",
        "label": "CPU Utilization (Avg)",
        "description": "The average percentage of CPU Utilization. For EC2, this is the average percentage of allocated EC2 compute units in use for an instance.",
        "data_type": "percentage",
        "type": "metric",
        "value": "0.840516"
      }
    ]
  },
  "offset": 0,
  "pagination": {
    "next": "02f296f8"
  },
  "limit": 2,
  "total_results": 2
}

利用データのレポートを作成し、後で結果を取り出す

このオプションは、（カーディナリティやタイムスパンが大きいため）レポート作成に時間がかかるレポートに最適です。 非同期レポート・フローのエンド・ポイントは、同期利用レポートと同じパラメーターを取りますが、レポートの内容を待って返す代わりに、リクエスト・トークンを返します。 現在の処理状態は、与えられたトークンの状態リソースをリクエストすることで取得される。 状態が "finished "と指定された場合、トークンの結果リソースをリクエストすることで、レポートの内容を取得することができる。 完全なデータフローの例は、結果リソースの説明の後に続く。

curl ‘https://api.cloudability.com/v3/reporting/util/enqueue?start_date=2022-01-01&end_date=2022-06-30&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’

回答例

{"id":31272850}

非同期レポートの状態を問い合わせる

非同期レポートの有効な状態には、待機中、実行中、エラー発生中、終了中がある。 状態は、以下のAPIコールで照会できます（enqueueコールから返される:idをレポートIDに置き換えてください）

curl https://api.cloudability.com/v3/reporting/reports/:id/state -u ‘[auth_token]:’

回答例

{"status":"running"}

Enqueueによって以前に生成されたレポートの取得

終了状態のレポートが検索できます。 これは標準的な利用報告オブジェクトを返します

curl ‘https://api.cloudability.com/v3/reporting/reports/:id/results’-u ‘[auth_token]:’]"

ページネーションに関する重要な注意：エンキューされたレポートは、同期利用レポートと同様の方法でページネーションを実装します。 唯一の違いは、ページのサイズが10,000行ではなく30,000行であることだ。 つまり、キューに入れられたレポートは、行数が30,000行を超えるまでページネーションが行われない。

サンプルレポート一覧

以下は、利用レポートAPIの使用に役立ついくつかのサンプル・レポートです。

相対的な日付による利用報告

curl ‘https://api.cloudability.com/v3/reporting/util/run?start_date=0+of+last+month&end_date=end+of+last+month&dimensions=date&metrics=total_bandwidth,avg_cpu_utilization&sort=dateASC&view_id=0’ -u ‘[auth_token]:’

インスタンス・タイプの利用傾向、CSVで返される

 curl -H ‘Accept: text/csv’ ‘https://api.cloudability.com/v3/reporting/util/run?start_date=2022-02-01&end_date=2022-02-28&dimensions=instance_size&metrics=utilization_hours,running_instances&sort=utilization_hoursDESC’ -u ‘[auth_token]:’

コンピュート最適化インスタンスの過少使用（複数のディメンジョンとフィルタを持つレポート）

curl 'https://api.cloudability.com/v3/reporting/util/run?start_date=2022-02-01&end_date=2022-02-28&dimensions=instance_size&metrics=utilization_hours%2Crunning_instances&sort=utilization_hoursDESC' -u '[auth_token]:'

典型的な利用レポート（打ち上げからの日数レポート）

curl ‘https://api.cloudability.com/v3/reporting/util/run?dimensions=launch_date&end_date=2022-08-30&filters=product_name%3D%3DAmazon%20Elastic%20Compute%20Cloud&limit=2&metrics=avg_cpu_utilization&relativePeriods=custom&sort=launch_dateDESC&start_date=2022-08-22&viewId=0’ -u ‘[auth_token]:’