使用情况报告终点

在线编辑

利用率报告端点用于分析 AWS EC2 实例的利用率模式。利用率分析采用来自 AWS Cloudwatch的数据，该数据呈现实例级别的详细信息，例如平均CPU利用率（百分比）、带宽和磁盘I/O。利用率分析对于可视化整体弹性以及实例是否需要调整或需要关闭非常有用。

利用率分析中提供的成本指标在 Cloudability 中使用按需费率计算，仅涵盖账单的计算部分（即计费实例小时数，但不包括带宽、存储等）。因此，它们只能用于趋势分析，而不能用于财务报告。请注意，该指标指的是成本（估算）。

请注意，为使利用分析系统能够访问利用数据，需要对各成员账户进行高级认证，以获得适当的 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 用于查询 util 报告
/reporting/reports/:id/state 用于检查排队报告的状态
/reporting/reports/:id/results 用于检索已完成的排队报告

注意：每个用户只能对报告/ util/ enqueue 端点发出 20 个请求。如果在此阈值下收到新请求，将返回 "429 响应"。

使用情况报告对象

results （数组）- 利用行对象列表，每行由报告的维度和指标组成
meta （对象）- 包含已运行报告的元信息的对象
- dates （对象）- 开始和结束日期字符串，标记报告的日期范围
- filters （数组）- 应用于报告的筛选器列表，包含详细信息
- metrics （数组）- 报告中返回的指标列表，包含详细信息
- dimensions （数组）- 报告中返回的维度列表，包含详细信息
- aggregates （数组）- 包含报告详细信息的汇总指标列表
- 偏移（数字）- 结果的起始位置。默认值为 0
- limit (number) - 可返回的最大利用行数
- total_results (number) - 已执行报告返回的总利用率行数

使用情况报告对象示例（审查示例）

{
  "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"
  },
    ]

获取可用措施清单

读取服务器识别的措施列表。措施包括可用于报告的维度和度量。只需在措施端点执行 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
]

* 请注意，这些操作符只能通过应用程序接口使用

运行使用情况报告

请求参数

注：关于开始/结束日期参数的说明：除了 YYYY-MM-DD 格式的静态日期字符串外，这些端点还支持 "本周初"、"本周末 "等相对日期本表下方列出了所有支持的相对日期字符串。例如，用户界面中的 "7 天前 "将使用 "7 天前 00:00:00 "的开始日期，而在应用程序接口中将使用 "今天 00:00:00 "的结束日期。还请注意，下面的相对日期字符串必须使用 "+"符号或"%20 "对字符串中的空格进行正确编码。例如，"end+of+last+month"。如果用户界面支持该用例，那么应用程序接口也将支持该用例

自变量	描述
开始日期（必填）	利用率报告的开始日期。格式： YYYY-MM-DD年-月-日
end_date （必填）	使用情况报告的结束日期。格式： YYYY-MM-DD年-月-日
尺寸（必填）	以逗号分隔的尺寸列表，包含在报告中。示例：维度=日期、实例大小
指标（必填）	以逗号分隔的指标列表，包含在报告中。示例：metrics=running_instances,usilization_hours
过滤器	应用于报告的筛选器。过滤器可以基于维度或指标。注意：过滤器查询参数仅用于单个过滤器。对多个过滤器使用多个查询参数。例如 filters=instance_size=@10xlarge 重要：比较运算符一般应使用 URL 编码（如上所述），以避免出现特殊字符问题
排序	以逗号分隔的措施列表，每个措施都用 ASC 或 DESC 表示顺序（顺序是必需的）。例如 sort=avg_cpu_utilizationASC,regionDESC
限制	要返回的最大行数。例如 limit=50
偏移量	结果的起始位置。例如 offset=100
图表	为图表目的格式化行数据（基于日期）。例如 chart=1
视图ID	如果省略，则应用用户的默认视图。不受限制的用户可以设置 view_id=0 删除视图。

注： v3 费用报告终端支持相对/动态日期字符串：

相对/动态日期字符串
"7天前的00:00:00"
"8天前的00:00:00"
"10天前的00:00:00"
"14天前的00:00:00"
"30天前的00:00:00"
"31天前的00:00:00"
"60天前的00:00:00"
"90天前的00:00:00"
"最后一天的开始"
"上周初"
"上月初"、"上月 0 日"
"上季度初"
"下半场开始"
"去年年初"
"日初"、"今初"
"本周初"、"本周初"
"月初"、"本月初"、"1"
"期初"、"本期期初"
"季度初"、"本季度初"
"半场开始"、"本半场开始"
"年初"、"今年年初"
"第二天开始"
"下周初"
"下月初"
"下季度初"
"下半场开始"
"明年年初"
"今天 00:00:00"
"00:00:00"
"23:59:59"
"昨天 00:00:00"
"昨天 23:59:59"
"最后一天结束"
"上周末"
"上月底"
"上季度末"
"上半场结束"
"去年年底"
"上周末至今"
"上月底至今"
"上季度末至今"
"去年年底至今"
"今天结束"、"今天结束"
"本周末"、"本周末"
"月底"、"本月底"
"季度末"、"本季度末"
"半场结束"、"本半场结束"
"年底"、"今年年底"
"第二天结束"
"下周末"
"下月底"
"下季度末"
"下半场结束"
"明年年底"

处理分页

为支持 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
}

生成使用数据报告并稍后检索结果

该选项非常适合需要较长时间才能返回的报告（因为卡片数量多或时间跨度大），可以触发报告生成，然后稍后再检索结果。异步报告流的终点采用与同步利用率报告相同的参数，但不是等待和返回报告内容，而是返回一个请求标记。当前处理状态可通过请求给定标记的状态资源来获取。当状态为 "完成 "时，可以通过请求令牌的结果资源来检索报告内容。完整数据流的示例紧随结果资源说明之后。

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]:’

生成报告时，用户可通过在请求中使用 "useDimensionNames" 选项（true/false）决定导出的业务映射列应使用业务映射ID还是映射名称作为列标题：

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&useDimensionNames=true' -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]:’]"

关于分页的重要说明：排队报告的分页方式与同步利用率报告类似。唯一不同的是，页面大小为 30,000 行，而不是 10,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]:’