使用上限設定API

簡介

Journey Orchestration的API支援5000個事件/秒,但某些外部系統或API的吞吐量無法相等。 這就是為什麼 Journey Orchestration 隨附稱為「限定API」的專用功能,可監控並限制我們對外部系統的執行率。

在資料來源設定期間,您將定義系統連線,以擷取將用於歷程的其他資訊,或用於動作定義,您將設定協力廠商系統的連線,以傳送訊息或API呼叫。 每次由歷程執行API呼叫時,即會查詢限定API,呼叫就會透過API引擎。 如果已定義限制,則會拒絕呼叫,且外部系統不會超載。

若為外部資料來源,則每秒的呼叫數上限設為15。 如果呼叫數超過每秒15次,則會捨棄剩餘的呼叫。 您可以提高私人外部資料來源的此限制。 請連絡Adobe,將端點納入允許清單中。 對於公用外部資料來源,則無法這麼做。 若要進一步了解整合外部系統時的最佳實務和防護,請參閱 頁面.

有關操作或資料源配置的詳細資訊,請參閱 關於動作關於資料來源

資源

注意

此 Journey Orchestration 可用的Swagger檔案中會說明設定API上限 此處.

若要將此API用於 Journey Orchestration 例項,您需要使用AdobeI/O主控台。 您可以依照以下步驟開始 開始使用Adobe開發人員控制台 然後使用本頁面中的部分。

若要測試並準備您的整合,可使用Postman集合 此處.

驗證

設定 API 存取

Journey Orchestration API存取權限是透過下列步驟設定。 以下各步驟在 Adobe I/O檔案.

注意

若要在Adobe I/O中管理憑證,請確定您 系統管理員 組織或 開發人員帳戶 (在Admin Console中)。

  1. 確認您擁有數位憑證,或視需要建立。 下列步驟需要憑證隨附的公開金鑰和私密金鑰。
  2. 建立新整合以 Journey Orchestration 服務 Adobe I/O並加以設定。 需要產品設定檔存取權 Journey Orchestration 和Adobe Experience Platform。 接著會產生您的認證(API金鑰、用戶端密碼……)。
  3. 建立JSON網頁代號(JWT) 從先前產生的憑證,並使用您的私密金鑰簽署。 JWT會對Adobe驗證身分並授予您API存取權所需的所有身分和安全資訊進行編碼。 此步驟在此中詳細說明
  4. 將JWT交換為存取權杖 透過POST要求或開發人員控制台介面。 此存取權杖必須用於API請求的每個標題中。

若要建立安全的服務對服務Adobe I/OAPI工作階段,對Adobe服務的每個要求都必須在授權標題中包含下列資訊。

curl -X GET https://journey.adobe.io/authoring/XXX \
 -H 'Authorization: Bearer <ACCESS_TOKEN>' \
 -H 'x-api-key: <API_KEY>' \
 -H 'x-gw-ims-org-id: <ORGANIZATION>'
  • <organization>:這是您的個人組織ID,由Adobe為每個執行個體提供一個組織ID:

    • <organization> :您的生產執行個體

    若要取得組織ID值,請洽詢您的管理員或Adobe技術聯絡人。 建立新整合時,您也可以將其擷取至Adobe I/O中,位於授權清單中(請參閱 Adobe I/O檔案)。

  • <access_token>:您的個人存取權杖,此權杖是透過POST要求交換JWT時擷取的。

  • <api_key>:您的個人API金鑰。 它會在建立與 Journey Orchestration 服務。

設定API說明上限

上限API可協助您建立、設定及監控上限設定。

方法 路徑 說明
POST list/endpointConfigs 獲取端點限定配置清單
POST /endpointConfigs 建立端點限定配置
POST /endpointConfigs/{uid}/deploy 部署端點限定配置
POST /endpointConfigs/{uid}/undeploy 取消部署端點限定配置
POST /endpointConfigs/{uid}/canDeploy 檢查是否可部署端點限定配置
PUT /endpointConfigs/{uid} 更新端點限定配置
GET /endpointConfigs/{uid} 擷取端點上限設定
DELETE /endpointConfigs/{uid} 刪除引入點限定配置

建立或更新設定時,會自動執行檢查,以保證有效負載的語法和完整性。
如果發生某些問題,操作會傳回警告或錯誤,以協助您修正設定。

端點設定

端點設定的基本結構如下:

{
    "url": "<endpoint URL>",  //wildcards are allowed in the endpoint URL
    "methods": [ "<HTTP method such as GET, POST, >, ...],
    "services": {
        "<service name>": { . //must be "action" or "dataSource" 
            "maxHttpConnections": <max connections count to the endpoint>
            "rating": {          
                "maxCallsCount": <max calls to be performed in the period defined by period/timeUnit>,
                "periodInMs": <integer value greater than 0>
            }
        },
        ...
    }
}

範例:

`{
  "url": "https://api.example.org/data/2.5/*",
  "methods": [
    "GET"
  ],
  "services": {
    "dataSource": {
      "maxHttpConnections": 30000,
      "rating": {
        "maxCallsCount": 5000,
        "periodInMs": 1000
      }
    }
  },
  "orgId": "<IMS Org Id>"
}

警告和錯誤

canDeploy 方法呼叫時,程式會驗證設定並傳回以其唯一ID識別的驗證狀態,其中一項為:

"ok" or "error"

潛在錯誤為:

  • ERR_ENDPOINTCONFIG_100:限定配置:遺失或無效的url
  • ERR_ENDPOINTCONFIG_101:限定配置:格式錯誤的url
  • ERR_ENDPOINTCONFIG_102:限定配置:格式錯誤的url:主機中不允許在url中使用通配符
  • ERR_ENDPOINTCONFIG_103:限定配置:缺少HTTP方法
  • ERR_ENDPOINTCONFIG_104:限定配置:未定義呼叫評級
  • ERR_ENDPOINTCONFIG_107:限定配置:最大呼叫計數無效(maxCallsCount)
  • ERR_ENDPOINTCONFIG_108:限定配置:最大呼叫計數無效(periodInMs)
  • ERR_ENDPOINTCONFIG_111:限定配置:無法建立端點配置:有效負載
  • ERR_ENDPOINTCONFIG_112:限定配置:無法建立端點配置:應為JSON裝載
  • ERR_AUTHORING_ENDPOINTCONFIG_1:無效的服務名稱 <!--<given value>-->:必須是「dataSource」或「action」

潛在警告是:

ERR_ENDPOINTCONFIG_106:限定配置:未定義的最大HTTP連接數:預設不限制

使用案例

在本節中,您會找到可在中執行以管理上限設定的五個主要使用案例 Journey Orchestration.

為協助您進行測試和設定,可使用Postman集合 此處.

此Postman集合已設定為共用透過 Adobe I/O主控台的整合 >試用>下載Postman,會產生包含所選整合值的Postman環境檔案。

下載並上傳至Postman後,您需要新增三個變數: {JO_HOST},{Base_Path}{SANDBOX_NAME}.

  • {JO_HOST} : Journey Orchestration 網關URL
  • {BASE_PATH} :API的進入點。 值為「/authoring」
  • {SANDBOX_NAME} :標題 x-sandbox-name (例如'prod'),此名稱對應於將進行API操作的沙箱名稱。 請參閱 沙箱概述 以取得更多資訊。

在下節中,您會找到Rest API呼叫排序清單以執行使用案例。

使用案例n°1: 建立和部署新的上限設定

  1. list
  2. 建立
  3. candeploy
  4. 部署

使用案例n°2: 更新並部署尚未部署的上限設定

  1. 清單
  2. get
  3. 更新
  4. candeploy
  5. 部署

用例n°3: 取消部署和刪除已部署的上限配置

  1. 清單
  2. 取消部署
  3. 刪除

使用案例n°4: 刪除已部署的上限配置。

在僅一個API呼叫中,您可以使用forceDelete參數來取消部署和刪除設定。

  1. 清單
  2. 刪除,使用forceDelete參數

使用案例n°5: 更新已部署的上限配置

  1. 清單
  2. get
  3. 更新
  4. 取消部署
  5. candeploy
  6. 部署

本頁內容