IBM Cloud Docs
管理路径

管理路径

您可以使用 IBM Cloud Metrics Routing UI、IBM Cloud Metrics Routing CLI、IBM Cloud Metrics Routing REST API 和 IBM Cloud Metrics Routing Terraform 提供程序管理账户中的路由。 路由定义规则,这些规则指示在区域中路由的度量值以及路由这些度量值的位置。

有关 IBM Cloud Metrics Routing 路径的更多信息,请参阅 路径

关于路由

您可以配置 IBM Cloud Metrics Routing 以将支持服务的不同地区生成的平台指标路由到目标目的地。

  • 您只能路由在 IBM Cloud Metrics Routing 可用的区域中生成的平台指标。 有关更多信息,请参阅区域

  • 如果您有法规和合规性要求,请检查路线规则是否符合这些要求。

IAM 访问权

您必须具有正确的 IAM 许可权才能管理路由。 有关信息,请参阅 管理 IAM 访问权

使用用户界面创建路由

使用用户界面创建路由的步骤如下。

  1. 登录您的 IBM Cloud 账户

  2. 单击 Menu 图标 Menu 图标 > Observability.

  3. 单击监控

  4. 单击 路由

  5. 单击路由选项卡。

  6. 单击 Create 打开创建路由页面。

  7. 为路线输入一个有意义的名称。

  8. 单击下一步

  9. 路由规则 中,修改 行动规则 1

    • 为规则选择 Send 以将指标路由到相关目标。

    • 为规则选择 Drop,以删除与此规则匹配的指标。

  10. 添加 包含筛选器,以确定路由到规则中指定的目标的指标。

选择所需的筛选器和条件,并指定要与包含筛选器匹配的值。

要添加多个包含筛选器,请单击 添加筛选器 以添加其他筛选器。

  1. 从列表中选择一个目标,添加 目标,以便与规则关联。 如果没有定义目标,请单击 添加目标 创建新目标。

  2. 单击 添加规则,为路由添加其他规则。

路由规则的顺序会影响路由行为。 规则按顺序处理,一旦某条规则被匹配,后面的规则将不再处理。

单击每个规则定义右侧的上下箭头,即可更改路由规则的顺序。

如果需要删除规则或筛选器,请单击与规则或筛选器相关的 Remove 图标。

每个路由最多可配置 10 条规则。

  1. 定义路线后,单击 下一步

  2. 检查路线定义,确保规则顺序符合预期。

  3. 单击创建

使用用户界面更新路线

使用用户界面更新路由的步骤如下。

  1. 登录您的 IBM Cloud 账户

  2. 单击 Menu 图标 Menu 图标 > Observability.

  3. 单击监控

  4. 单击 路由

  5. 单击路由选项卡。

  6. 确定要更新的路由,然后单击 Actions 图标.

  7. 单击 Rename 重命名路由。

  8. 单击 Edit 更新路由规则。

  9. 路由规则中,修改规则的 操作

    • 为规则选择 Send 以将指标路由到相关目标。

    • 为规则选择 Drop,以删除与此规则匹配的指标。

  10. 添加或修改 包含过滤器,以确定路由到规则中指定的目标的指标。

选择所需的筛选器和条件,并指定要与包含筛选器匹配的值。

要添加多个包含筛选器,请单击 添加筛选器 以添加其他筛选器。

  1. 从列表中选择一个目标,修改 目标,以便与规则关联。 如果没有定义目标,请单击 添加目标 创建新目标。

  2. 单击 添加规则,为路由添加其他规则。

路由规则的顺序会影响路由行为。 规则按顺序处理,一旦某条规则被匹配,后面的规则将不再处理。

单击每个规则定义右侧的上下箭头,即可更改路由规则的顺序。

如果需要删除规则或筛选器,请单击与规则或筛选器相关的 Remove 图标。

每个路由最多可配置 10 条规则。

  1. 单击更新对路线进行更改。

使用用户界面查看路线

要使用用户界面查看路线,请执行以下操作。

  1. 登录您的 IBM Cloud 账户

  2. 单击 Menu 图标 Menu 图标 > Observability.

  3. 单击监控

  4. 单击 路由

  5. 单击路由选项卡。

    已配置的路由将被列出。 路由的顺序不会影响路由行为,因为它们是独立处理的。

    每个路由都显示路由名称和规则。

    路由页面还会显示 路由指南,其中包含有关配置路由的其他信息。

使用用户界面删除路线

使用用户界面删除路由的步骤如下。

  1. 登录您的 IBM Cloud 账户

  2. 单击 Menu 图标 Menu 图标 > Observability.

  3. 单击监控

  4. 单击 路由

  5. 单击路由选项卡。

  6. 确定要删除的路径,然后单击 Actions 图标

  7. 单击 Delete 删除整个路线。 删除路由前必须输入路由名称。

CLI 先决条件

在使用 CLI 管理路由之前,请完成以下步骤:

  1. 安装 IBM Cloud CLI

  2. 安装 IBM Cloud Metrics Routing CLI

  3. 登录到 IBM Cloud。 运行以下命令: ibmcloud login

使用 CLI 创建路由

使用此命令创建路由。

路径名在帐户中是唯一的。

ibmcloud metrics-router route create --name ROUTE_NAME ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

命令选项

--name ROUTE_NAME

要对路由指定的名称。

请勿在任何资源名称中包含任何个人标识信息 (PII)。

--rules RULES

JSON 格式的规则数组定义 (用单引号括起),用于定义如何路由度量。 有关更多信息,请参阅 定义路由规则

--file RULES_DEFINITION_JSON_FILE

JSON 文件,其中包含用于定义如何路由度量的路由规则。 有关更多信息,请参阅 定义路由规则

--output FORMAT

当前支持的格式为 JSON。 如果指定此项,那么将以 JSON 格式返回输出。 如果未指定 "JSON,输出将以表格格式返回。

help | --help | -h

列出可用于该命令的选项。

示例

以下是使用 ibmcloud metrics-router route create 命令的示例。

此示例显示成功创建路由的示例。

ibmcloud mr route create --name target1 --rules '[{"action": "send", "targets":[{"id":"551957a7-c1e3-4160-84d8-4268709f6743"}]}]'
OK
Route
Name:         target1
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:14:21.460Z

使用 CLI 更新路由

使用此命令更新路由。 与最初创建路由时不同的任何指定值都将更新为命令中指定的值。

ibmcloud metrics-router route update --route ROUTE [--name ROUTE_NAME] ( --rules RULES |  --file RULES_DEFINITION_JSON_FILE ) [--output FORMAT] [--force]

命令选项

--route ROUTE

标识或当前路由名称。

--name route_NAME

要对路由指定的名称。

请勿在任何资源名称中包含任何个人标识信息 (PII)。

--rules RULES

JSON 格式的规则数组定义 (用单引号括起),用于定义如何路由度量。 有关更多信息,请参阅 定义路由规则

--file RULES_DEFINITION_JSON_FILE

JSON 文件,其中包含用于定义如何路由度量的路由规则。 有关更多信息,请参阅 定义路由规则

--output FORMAT

当前支持的格式为 JSON。 如果指定此项,那么将以 JSON 格式返回输出。 如果未指定 "JSON,输出将以表格格式返回。

help | --help | -h

列出可用于该命令的选项。

示例

以下是使用 ibmcloud metrics-router route update --route my-route --name my-new-route-name 命令的示例。

ibmcloud mr route update --route target1 --name target2
OK
Route
Name:         target2
ID:           06a29ca2-40f5-4371-ae3c-76a896577bd3
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:06a29ca2-40f5-4371-ae3c-76a896577bd3
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T21:14:21.460Z
Updated At:   2023-05-30T21:19:40.953Z

使用 CLI 删除路由

使用此命令删除路由。

ibmcloud metrics-router ROUTE rm --route route [--force]

命令选项

--route ROUTE
路由的标识或名称。
--force | -f
将删除路由而不向用户提供任何其他提示。
help | --help | -h
列出可用于该命令的选项。

示例

以下是使用 ibmcloud metrics-router route rm --route xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx 命令的示例。

Are you sure you want to remove the route with route ID xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx? [y/N]>y
OK
Route with name xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx was successfully removed.

使用 CLI 获取有关路由的信息

使用此命令可获取有关 IBM Cloud Metrics Routing 区域的路由的信息。

ibmcloud metrics-router ROUTE get --route route [--output FORMAT]

命令选项

--route ROUTE
路由的标识或名称。
--output FORMAT
当前支持的格式为 JSON。 如果指定此项,那么将以 JSON 格式返回输出。 如果未指定 "JSON,输出将以表格格式返回。
help | --help | -h
列出可用于该命令的选项。

示例

以下是使用 ibmcloud metrics-router route get --route new-route-name 命令显示路由的示例。

ibmcloud mr route get --route route-all
OK
Route
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

列出区域中的所有路径

使用此命令可列出 IBM Cloud Metrics Routing 区域的已配置路径。

ibmcloud metrics-router route ls [--output FORMAT]

命令选项

--output FORMAT
当前支持的格式为 JSON。 如果指定此项,那么将以 JSON 格式返回输出。 如果未指定 "JSON,输出将以表格格式返回。
help | --help | -h
列出可用于该命令的选项。

示例

以下是使用 ibmcloud metrics-router route ls 命令的示例。

ibmcloud mr route ls
OK
Routes
Name:         route-all
ID:           f22e9cb6-2fcd-456d-9cf2-27813b1cc375
CRN:          crn:v1:bluemix:public:metrics-router:global:a/xxxx::route:f22e9cb6-2fcd-456d-9cf2-27813b1cc375
Rule 0:       [[551957a7-c1e3-4160-84d8-4268709f6743(mon-std)], []]
Created At:   2023-05-30T08:04:53.183Z
Updated At:   2023-05-30T08:53:22.824Z

API 路径和操作

下表列出了管理路由时可以执行的操作:

使用IBM Cloud Metrics Routing进行路由操作。REST API
操作 REST API 方法 API_URL
创建路径 POST <ENDPOINT>/api/v3/routes
更新路径 PATCH <ENDPOINT>/api/v3/routes/<route_ID>
删除路径 DELETE <ENDPOINT>/api/v3/routes/<route_ID>
读取路径 GET <ENDPOINT>/api/v3/routes/<route_ID>
列出所有路径 GET <ENDPOINT>/api/v3/routes

您可以使用专用端点和公共端点来管理路由。 有关可用的 ENDPOINTS 列表的更多信息,请参阅 端点

  • 您可以使用以下格式的 API 端点来管理来自专用网络的路由: https://private.REGION.metrics-router.cloud.ibm.com

  • 您可以使用以下格式的 API 端点来管理来自公用网络的路由: https://REGION.metrics-router.cloud.ibm.com

  • 您可以通过更新帐户设置来禁用公共端点。 有关更多信息,请参阅 配置路径和区域设置

有关 REST API 的更多信息,请参阅 路由

API 先决条件

要进行 API 调用以管理路由,请完成以下步骤:

  1. 获取 IAM 访问令牌。 有关更多信息,请参阅 检索 IAM 访问令牌
  2. 确定您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点

使用 API 创建路由

您可以使用以下cURL命令创建路由:

路径名在帐户中是唯一的。 不能复用路由名称来配置多个目标。

curl -X POST <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

Where

<ENDPOINT>

您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点

ROUTE_NAME

要对路由指定的名称。

请勿在任何资源名称中包含任何个人标识信息 (PII)。

RULES

JSON 格式的规则数组定义 (用单引号括起),用于定义如何路由度量。 有关更多信息,请参阅 定义路由规则

例如,可以使用以下 cURL 请求来创建路由:

curl -X POST https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My-route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
  }'

使用 API 更新路由

您可以修改路径和规则的名称。 与最初创建路由时不同的任何指定值都将更新为请求中指定的值。

更新路由时,必须在请求的数据部分中包含路由信息。

  • 必须传递所有字段。
  • 更新需要更改的字段。

路径名在帐户中是唯一的。 不能复用路由名称来配置多个目标。

您可以使用以下 cURL 命令来更新路由:

curl -X PATCH <ENDPOINT>/api/v3/routes/ROUTE_ID -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "ROUTE_NAME",
    "rules": [
      RULES
    ]
  }'

Where

<ENDPOINT>

您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点

ROUTE_ID

路由标识。

ROUTE_NAME

路由的名称。 名称的最大长度为 256 个字符。

请勿在任何资源名称中包含任何个人标识信息 (PII)。

RULES

JSON 格式的规则数组定义 (用单引号括起),用于定义如何路由度量。 有关更多信息,请参阅 定义路由规则

例如,您可以使用以下 cURL 请求在达拉斯创建路由:

curl -X PATCH https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json" -d '{
    "name": "My route",
    "rules": [
      {
        "action": "send",
        "targets": [
          {
            "id": "50375218-7cff-4234-bbb4-171bebab8408"
          },
          {
            "id": "c7519d8a-5f97-498b-a229-8542f60955cd"
          }
        ],
        "inclusion_filters": [
          {
            "operand": "location",
            "operator": "is",
            "values": ["us-east"]
          },
          {
            "operand": "service_name",
            "operator": "in",
            "values": ["codeengine","container-registry"]
          }
        ]
      }
    ]
    }
  }'

使用 API 删除路由

可以使用以下 cURL 命令来删除路由:

curl -X DELETE <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>
您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点
<route_ID>
路由标识。

例如,可以使用以下 cURL 请求来删除标识为 00000000-0000-0000-0000-000000000000 的路由:

curl -X DELETE https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

使用 API 查看路由

您可以使用以下 cURL 命令来查看 1 路由的配置详细信息:

curl -X GET <ENDPOINT>/api/v3/routes/<route_ID> -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

<ENDPOINT>
您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点
<route_ID>
路由标识。

例如,您可以运行以下 cURL 请求以获取有关标识为 00000000-0000-0000-0000-000000000000 的路由的信息:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes/00000000-0000-0000-0000-000000000000 -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

使用 API 列出所有路由

您可以使用以下 cURL 命令来查看所有路由:

curl -X GET <ENDPOINT>/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

Where

  • <ENDPOINT> 是您计划在其中配置或管理路由的区域中的 API 端点。 有关更多信息,请参阅 端点

例如,您可以运行以下 cURL 请求以获取有关达拉斯中定义的路由的信息:

curl -X GET https://private.us-south.metrics-router.cloud.ibm.com/api/v3/routes -H "Authorization: $ACCESS_TOKEN" -H "content-type: application/json"

HTTP 响应代码

使用 IBM Cloud Metrics Routing REST API 时,可以获取标准 HTTP 响应代码以指示方法是否成功完成。

  • 200 响应始终指示成功。
  • 4xx 响应指示失败。
  • 5xx 响应指示内部系统错误。

请参阅下表以了解一些 HTTP 响应代码:

HTTP 响应代码列表
状态码 状态 描述
200 OK 请求已成功。
201 OK 请求已成功。 将创建资源。
400 错误请求 请求失败。 您可能缺少必需的参数。
401 未授权 API 请求中使用的 IAM 令牌无效或已到期。
403 禁止 由于许可权不足,因此禁止执行此操作。
404 找不到 请求的资源不存在或已被删除。
429 请求次数太多 过多请求过快地命中 API。
500 内部服务器错误 在 IBM Cloud Metrics Routing 处理中发生错误。