文档 Journey Optimizer Journey Optimizer 指南

使用 API 限制

最近更新： 2026年4月29日

主题：
Journeys
API

创建对象：

Beginner
Developer

The Throttling API helps you create, configure and monitor your throttling configurations in order to limit the number of events sent per second.

This section provides global information on how to work with the API. A detailed API description is available in Adobe Journey Optimizer APIs documentation.

必读

One configuration per organization: Only one configuration is currently allowed per organization. A configuration must be defined on a production sandbox (given through x-sandbox-name in the headers).
Organization-level application: A configuration is applied at organization level.
API limit handling: When the limit set in the API is reached, further events are queued for up to 6 hours. 无法修改此值。
maxHttpConnectionsparameter: The maxHttpConnections parameter is an optional parameter available in Capping API only allowing you to restrict the number of connections Journey Optimizer will open to the external system. Learn how to work with the Capping API

If you want to restrict the number of connections but also throttle those external calls, you can configure two configurations, one throttling and one capping, on the same endpoint. Both configurations can co-exist for one endpoint. To set ‘maxHttpConnections’ for a throttled endpoint, use the Throttling API to set the throttling threshold and the Capping API to set the ‘maxHttpConnections’. When calling the Capping API, you can set the capping threshold to something higher than the throttling threshold so the capping rule will effectively never come into play.

Throttling API description & Postman collection description

The table below lists the available commands for the throttling API. Detailed information including request samples, parameters, and response formats is available in the Adobe Journey Optimizer APIs documentation.

方法

路径

描述

POST

list/throttlingConfigs

获取限制配置列表

POST

/throttlingConfigs

创建限制配置

POST

/throttlingConfigs/{uid}/deploy

部署限制配置

POST

/throttlingConfigs/{uid}/undeploy

取消部署限制配置

POST

/throttlingConfigs/{uid}/canDeploy

检查是否可以部署限制配置

PUT

/throttlingConfigs/{uid}

更新限制配置

GET

/throttlingConfigs/{uid}

检索限制配置

DELETE

/throttlingConfigs/{uid}

删除限制配置

In addition, a Postman collection is available here to help you in your testing configuration.

This collection has been set up to share the Postman Variable collection generated via Adobe I/O Console’s Integrations > Try it out > Download for Postman, which generates a Postman Environment file with the selected integrations values.

下载并上传到 Postman 后，您需要添加三个变量：{JO_HOST}、{BASE_PATH} 和 {SANDBOX_NAME}。

{JO_HOST} : Journey Optimizer Gateway URL.
{BASE_PATH}：API 的入口点。
{SANDBOX_NAME}：标头 x-sandbox-name（例如，“prod”），对应将执行 API 操作的沙盒名称。有关更多信息，请参阅沙盒概述。

限制配置 configuration

以下是限制配置的结构。 name 和 description 属性是可选项。

{
    "name": "<given name - free text>",
    "description": "<given description - free text>"
    "urlPattern": "<endpoint URL - wildcards are allowed>",
    "methods": [ "<HTTP method such as GET, POST, PUT>" ],
    "maxThroughput": <max call throughput>
}

示例：

{
  "name": "throttling-config-external",
  "description": "example of throttling config for an external endpoint",
  "urlPattern": "https://api.example.org/data/2.5/*",
  "methods": ["POST", "PUT"],
  "maxThroughput": 4000
}

IMPORTANT

The configuration will only be active after calling the deploy endpoint.

错误

创建或更新配置时，该流程会验证给定配置并返回由其“唯一 ID”标识的验证状态，这可以是：

"ok" or "error"

IMPORTANT

属性 maxThroughput、urlPattern 和 methods 是必填项。

maxThroughput 的值必须在 200-5000 范围内。

创建、删除或部署限制配置时，可能会出现以下错误：

ERR_THROTTLING_CONFIG_100：限制配置：<mandatory attribute>必需
ERR_THROTTLING_CONFIG_101：限制配置：maxThroughput 是必填项，且必须大于或等于 200 且小于或等于 5,000
ERR_THROTTLING_CONFIG_104：限制配置：格式错误的 URL 模式
ERR_THROTTLING_CONFIG_105：限制配置：URL 模式的主机部分不允许使用通配符
ERR_THROTTLING_CONFIG_106：限制配置：无效负载
THROTTLING_CONFIG_DELETE_FORBIDDEN_ERROR: 1456，“无法删除已部署的限制配置。请在删除之前取消部署”
THROTTLING_CONFIG_DELETE_ERROR: 1457，“无法删除限制配置：发生意外错误”
THROTTLING_CONFIG_DEPLOY_ERROR: 1458，“无法部署限制配置：发生意外错误”
THROTTLING_CONFIG_UNDEPLOY_ERROR: 1459，“无法取消部署限制配置：发生意外错误”
THROTTLING_CONFIG_GET_ERROR: 1460，“无法获取限制配置：发生意外错误”
THROTTLING_CONFIG_UPDATE_NOT_ACTIVE_ERROR: 1461，“无法更新限制配置：运行时版本处于不活动状态”
THROTTLING_CONFIG_UPDATE_ERROR: 1462，“无法更新限制配置：发生意外错误”
THROTTLING_CONFIG_NON_PROD_SANDBOX_ERROR: 1463，“禁止对限制配置执行操作：非生产沙盒”
THROTTLING_CONFIG_CREATE_ERROR: 1464，“无法创建限制配置：发生意外错误”
THROTTLING_CONFIG_CREATE_LIMIT_ERROR: 1465，“无法创建限制配置：仅允许为每个组织使用一个配置”
THROTTLING_CONFIG_ALREADY_DEPLOYED_ERROR: 14466，“无法部署限制配置：已部署”
THROTTLING_CONFIG_NOT_FOUND_ERROR: 14467，“找不到限制配置”
THROTTLING_CONFIG_NOT_DEPLOYED_ERROR: 14468，“无法取消部署限制配置：尚未部署”

错误示例

尝试在非生产沙盒上创建配置时：

{
    "status": 400,
    "error": "{\"code\":1463,\"family\":\"INPUT_OUTPUT_ERROR\",\"message\":\"Operation not allowed on throttling config: non prod sandbox\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.service.authoring.restapis.v1_0.ThrottlingConfigService:384\",\"schema\":\"throttlingConfigs$ui-tests\"}",
    "requestId": "5sgnAYXs8mpswwjAFEIaAU2faQYbtyHc"
}

如果给定的沙盒不存在：

{
    "status": 500,
    "error": "{\"code\":4000,\"family\":\"INTERNAL_ERROR\",\"message\":\"INTERNAL ERROR\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.common.exceptions.ApiErrorException:43\"}",
    "requestId": "04ZJ4e5ki4bYs3lfO17a7hovRGewjvdK"
}

尝试创建其他配置时：

{
    "status": 400,
    "error": "{\"code\":1465,\"family\":\"INPUT_OUTPUT_ERROR\",\"message\":\"Can't create throttling config: only one config allowed per org\",\"service\":\"vyg-authoring-api\",\"version\":\"ed87515\",\"context\":\"com.adobe.voyager.service.authoring.restapis.v1_0.ThrottlingConfigService:108\",\"schema\":\"throttlingConfigs$prod\"}",
    "requestId": "A7ezT8JhOQT4WIAf1Fv7K2wCDA8281qM"
}

运行时级别的配置生命周期 config

取消部署配置后，该配置在运行时级别被标记为不活动，并且在 24 小时内将继续处理待处理事件。然后，会在运行时服务中删除它。

取消部署配置后，可以更新和重新部署配置。这将创建新的运行时配置，在即将执行的操作中将使用该配置。

更新已部署的配置时，会立即使用新值。底层系统资源将自动调整。与取消部署然后重新部署配置相比，这是最佳选择。

响应示例 responses

创建 - POST

{
    "canDeploy": {
        "validationStatus": "ok"
    },
    "createdElement": {
        "name": "throttling-config-external",
        "description": "example of throttling config for an external endpoint",
        "urlPattern": "https://api.example.org/data/2.5/*",
        "methods": [
            "PUT",
            "POST"
        ],
        "maxThroughput": 4000,
        "orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
        "sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
        "sandboxName": "prod",
        "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
        "metadata": {
            "createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "createdAt": "2023-03-22T10:48:16.099647Z",
            "lastModifiedAt": "2023-03-22T10:48:16.099647Z"
        },
        "state": "created",
        "authoringFormatVersion": "1.0"
    },
    "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
    "uri": "/voyager/apis/throttlingConfigs/043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
    "resStatus": "created"
}

更新 - PUT

{
    "updatedElement": {
        "_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
        "name": "throttling-config-external -- optional",
        "description": "example of throttling config for an external endpoint -- optional",
        "urlPattern": "https://api.example.org/data/2.5/*",
        "methods": [
            "POST"
        ],
        "maxThroughput": 5000,
        "orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
        "sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
        "sandboxName": "prod",
        "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
        "metadata": {
            "createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "createdAt": "2023-03-22T10:48:16.099647Z",
            "lastModifiedAt": "2023-03-22T11:39:14.212983Z"
        },
        "state": "updated",
        "authoringFormatVersion": "1.0",
        "hasBeenDeployed": false
    },
    "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
    "uri": "/voyager/apis/throttlingConfigs/043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
    "resStatus": "updated",
    "canDeploy": {
        "validationStatus": "ok"
    }
}

读取（更新后）- GET

{
    "result": {
        "_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
        "name": "throttling-config-external -- optional",
        "description": "example of throttling config for an external endpoint -- optional",
        "urlPattern": "https://api.example.org/data/2.5/*",
        "methods": [
            "POST"
        ],
        "maxThroughput": 5000,
        "orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
        "sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
        "sandboxName": "prod",
        "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
        "metadata": {
            "createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "createdAt": "2023-03-22T10:48:16.099647Z",
            "lastModifiedAt": "2023-03-22T11:39:14.212983Z"
        },
        "state": "updated",
        "authoringFormatVersion": "1.0",
        "hasBeenDeployed": false
    }
}

读取（部署后）- GET

{
    "result": {
        "_id": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6_8872a010-f91e-11ea-895c-11ef8f98ba52",
        "orgId": "AC202A3A5F615BD30A495FDE@AdobeOrg",
        "sandboxId": "8872a010-f91e-11ea-895c-11ef8f98ba52",
        "sandboxName": "prod",
        "uid": "043a1aea-2dfd-4965-b93a-cb9a1eced0e6",
        "urlPattern": "https://api.example.org/data/2.5/*",
        "methods": [
            "POST"
        ],
        "maxThroughput": 5000,
        "authoringFormatVersion": "1.0",
        "name": "throttling-config-external -- optional",
        "description": "example of throttling config for an external endpoint -- optional",
        "version": "1.0",
        "state": "deployed",
        "metadata": {
            "createdBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "createdById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "createdAt": "2023-03-22T10:48:16.099647Z",
            "lastModifiedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "lastModifiedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "lastModifiedAt": "2023-03-22T11:39:14.212983Z",
            "lastDeployedBy": "dacce1c3-d08b-4862-b434-2a4449c7e642@techacct.adobe.com",
            "lastDeployedById": "309F2A46640B0B300A495C83@techacct.adobe.com",
            "lastDeployedAt": "2023-03-22T11:46:07.532648Z"
        },
        "hasBeenDeployed": true
    }
}

用例 uc

本节列出了在Journey Optimizer中管理限制配置的关键用例，以及实施用例所需的相关API命令。

有关每个API命令的详细信息，请参见API描述和Postman集合。

创建和部署新限制配置

要使用的API调用：

list — 检索现有配置。
create — 创建新配置。
candeploy — 检查配置是否可以部署。
deploy — 部署配置。

更新和部署限制配置（尚未部署）

要使用的API调用：

list — 检索现有配置。
get — 获取特定配置的详细信息。
update — 修改配置。
candeploy — 检查部署资格。
deploy — 部署配置。

取消部署和删除已部署的限制配置

要使用的API调用：

list — 检索现有配置。
undeploy — 取消部署配置。
delete — 删除配置。

删除已部署的限制配置

在仅一个API调用中，您可以使用forceDelete参数取消部署和删除配置。

要使用的API调用：

list — 检索现有配置。
delete（带forceDelete参数） — 强制在单个步骤中删除已部署的配置。

更新已部署的限制配置

note
NOTE
在更新之前，无需取消部署配置

要使用的API调用：

list — 检索现有配置。
get — 获取特定配置的详细信息。
update — 修改配置。

recommendation-more-help

journey-optimizer-help