Docs4dev
Docs
opentsdb / 2.3 / reference / api_http-put.html

/api/put

该端点允许通过 HTTP 将数据存储在 OpenTSDB 中，作为 Telnet 接口的替代方法。放置请求只能通过与 POST 方法关联的内容执行。内容的格式取决于所选的序列化器。但是，有一些常见的参数和响应，如下所述。

为了节省带宽，put API 允许 Client 端在单个请求中存储多个数据点。数据点不必以任何方式关联。每个数据点都是单独处理的，并且一个数据出现错误不会影响良好数据的存储。这意味着，如果您的请求有 100 个数据点，而其中 1 个有错误，则仍将写入 99 个数据点，而其中一个将被拒绝。有关确定未存储哪个数据点的详细信息，请参见下面的“响应”部分。

Note

如果无法解析为请求提供的内容，例如缺少引号或花括号的 JSON 内容，则所有数据点都将被丢弃。 API 将返回错误，并提供有关错误原因的详细信息。

尽管该 API 确实支持每个请求多个数据点，但只有在处理完每个 API 后，该 API 才会返回。这意味着必须验证度量标准和标签名称/值，解析值并将数据排队存储。如果您的放置请求具有大量数据点，则 API 可能需要花费很长时间才能响应，尤其是在 OpenTSDB 必须为标记名称或值分配 UID 的情况下。因此，最好限制每个请求的最大数据点数。每个请求 50 美元是一个很好的起点。

另一个建议是在 HTTPClient 端上启用保持活动状态，以便您每次放置数据时都可以重新使用与服务器的连接。

Note

当使用 HTTP 放置请求时，如果 HTTPClient 端自动将大型请求分解为较小的数据包，则可能需要启用对块的支持。例如，CURL 将分解大于 2 个或 3 个数据点的消息，并且默认情况下，OpenTSDB 禁用块支持。通过在配置文件中将tsd.http.request.enable_chunked设置为 true 来启用它。

Note

如果tsd.mode设置为ro，则/api/put端点将不可用，并且所有调用都将返回 404 错误。

Verbs

  • POST

Requests

可以提供一些查询字符串参数，这些参数会更改对放置请求的响应：

Name Data Type Required Description Default QS RW Example
summary Present Optional 是否返回摘要信息 false summary /api/put?summary
details Present Optional 是否返回详细信息 false details /api/put?details
sync Boolean Optional 在返回结果之前是否 await 数据刷新到存储。 false sync /api/put?sync
sync_timeout Integer Optional 超时(以毫秒为单位)，await 数据刷新到存储，然后返回错误。发生超时时，使用details标志将告诉您有多少个数据点失败以及有多少成功。也必须提供sync才能生效。值为 0 表示写入将不会超时。 0 sync_timeout /api/put/?sync&sync_timeout=60000

如果查询字符串中同时包含detailed和summary，则 API 将以detailed信息进行响应。

下面的字段和示例引用默认的 JSON 序列化程序。

Name Data Type Required Description Default QS RW Example
metric String Required 您要存储的 Metrics 的名称 W sys.cpu.nice
timestamp Integer Required Unix 时代风格的时间戳，以秒或毫秒为单位。时间戳不得包含非数字字符。 W 1365465600
value 整数，浮点数，字符串 Required 要为此数据点记录的值。它可以带引号或不带引号，并且必须符合 OpenTSDB 值规则：../../user_guide/writing W 42.5
tags Map Required 标签名称/标签值对的 Map。必须至少提供一对。 W {"host":"web01"}

示例单个数据点放置

您可以在请求中提供一个数据点：

{
    "metric": "sys.cpu.nice",
    "timestamp": 1346846400,
    "value": 18,
    "tags": {
       "host": "web01",
       "dc": "lga"
    }
}

示例多个数据点放置

多个数据点必须包含在数组中：

[
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 18,
        "tags": {
           "host": "web01",
           "dc": "lga"
        }
    },
    {
        "metric": "sys.cpu.nice",
        "timestamp": 1346846400,
        "value": 9,
        "tags": {
           "host": "web02",
           "dc": "lga"
        }
    }
]

Response

默认情况下，如果所有数据点都已成功存储，则 put 终结点将使用204 HTTP 状态代码进行响应，并且不显示任何内容。如果一个或多个数据点有错误，则 API 将返回400，内容中包含错误消息。

出于调试目的，您可以要求响应包括成功存储和失败存储了多少个数据点的摘要，或者获取有关无法存储哪些数据点以及原因的详细信息，以便您可以修复 Client 端代码。同样，数据点的错误将记录在 TSD 的日志文件中，因此您可以在其中查找问题。

summary或detailed响应中包含的字段包括：

Name Data Type Description
success Integer 已成功排队存储的数据点数
failed Integer 不能排队存储的数据点数
errors Array 失败的数据点列表以及原因。仅出现在details响应中。

带有摘要的示例响应

{
    "failed": 1,
    "success": 0
}

带有详细信息的示例响应

{
    "errors": [
        {
            "datapoint": {
                "metric": "sys.cpu.nice",
                "timestamp": 1365465600,
                "value": "NaN",
                "tags": {
                    "host": "web01"
                }
            },
            "error": "Unable to parse value to a number"
        }
    ],
    "failed": 1,
    "success": 0
}