文档CommerceAEM Assets集成

自定义自动匹配

最近更新： 2026年10月12日

创建对象：

  • 用户

如果默认自动匹配策略（OOTB自动匹配）与您的特定业务要求不一致，请选择自定义匹配选项。 此选项支持使用Adobe Developer App Builder开发自定义匹配器应用程序，该应用程序可处理复杂的匹配逻辑，或者处理来自无法将元数据填充到AEM Assets中的第三方系统的资源。

配置自定义自动匹配

  1. 在Commerce管理员中，导航到​Store >配置> ADOBE SERVICES > AEM Assets Integration。

  2. 选择​ Custom Matcher ​作为匹配规则。

  3. 当您选择此匹配规则时，管理员会显示用于配置​ 端点 ​和自定义匹配逻辑所需​ 身份验证参数 ​的其他字段。

workspace.json

Adobe I/O Workspace Configuration​字段通过导入App Builder workspace.json配置文件提供了一种配置自定义匹配器的简化方法。

您可以从Adobe Developer Console下载workspace.json文件。 该文件包含App Builder工作区的所有凭据和配置详细信息。

示例workspace.json
code language-json 
{
  "project": {
    "id": "project_id",
    "name": "project_name",
    "title": "title_name",
    "org": {
      "id": "id",
      "name": "Organization_name",
      "ims_org_id": "ims_id"
    },
    "workspace": {
      "id": "workspace_id",
      "name": "workspace_name_id",
      "title": "workspace_title_id",
      "action_url": "https://action_url.net",
      "app_url": "https://app_url.net",
      "details": {
        "credentials": [
          {
            "id": "credential_id",
            "name": "credential_name_id",
            "integration_type": "oauth_server_to_server",
            "oauth_server_to_server": {
              "client_id": "client_id",
              "client_secrets": ["secret"],
              "technical_account_email": "xx@technical_account_email.com",
              "technical_account_id": "technical_account_id",
              "scopes": [
                "AdobeID",
                "openid",
                "read_organizations",
                "additional_info.projectedProductContext",
                "additional_info.roles",
                "adobeio_api",
                "read_client_secret",
                "manage_client_secrets"
              ]
            }
          }
        ],
        "services": [
          {
            "code": "AdobeIOManagementAPISDK",
            "name": "I/O Management API"
          }
        ],
        "runtime": {
          "namespaces": [
            {
              "name": "namespace_name",
              "auth": "example_auth"
            }
          ]
        },
        "events": {
          "registrations": []
        },
        "mesh": {}
      }
    }
  }
}
  1. 将workspace.json文件从App Builder项目拖放到​ Adobe I/O Workspace Configuration ​字段中。 或者，您可以单击浏览并选择文件。

Workspace配置 {width="600" modal="regular"}

  1. 系统自动：

    • 验证JSON结构
    • 提取和填充OAuth凭据
    • 获取工作区的可用运行时操作
    • 填充​ Product to Asset URL ​和​ Asset to Product URL ​字段的下拉列表选项

  2. 从每个流的下拉菜单中选择相应的运行时操作。

  3. 单击​Save Config。

异步配置保存

如果您的Commerce实例启用了异步配置保存选项，则配置更改将排入队列并由异步使用者应用，而不是立即保存在同一请求中。 要在此模式下上载自定义自动匹配的workspace.json文件，请依次完成以下步骤：

  1. 确认Commerce异步配置保存已启用。

  2. 从管理员转到​Stores > Settings > Configuration > Adobe Services > AEM Assets Integration。

  3. 上传当前的App Builder workspace.json文件。

  4. 保存配置。

  5. 等待异步配置使用者完成保存处理。

  6. 验证OAuth值和依赖的集成配置。

  7. 验证外部匹配程序注册是否反映了更新。

NOTE
如果禁用了异步配置保存，则会应用正常的同步保存行为，并且您不需要等待队列使用者。

异步配置保存疑难解答

症状
要做什么
保存后，OAuth值保持不变
确认您正在运行AEM Assets集成扩展版本1.4.7或更高版本，上传新的workspace.json文件，并等待队列处理完成，然后再次检查值。
上传无效后，保存失败
验证文件是否为格式正确的workspace.json文件并包含预期的App Builder凭据。
未上传任何文件
现有的存储配置保持不变。
外部匹配程序注册不会更新
检查队列使用者是否已完成处理，查看Commerce日志，并确认外部匹配程序注册状态。
已禁用异步配置保存
常规的同步保存行为适用；此故障排除部分不适用。
NOTE
如果您开发了AEM Assets集成的配置观察器，请不要依赖于原始HTTP请求参数。 异步配置保存和其他程序化配置保存可以在没有管理员请求上下文的情况下执行观察程序。

自定义匹配器API端点

当您使用App Builder生成自定义匹配程序应用程序时，该应用程序必须公开以下端点：

  • App Builder资源到产品URL​端点
  • App Builder产品到资源URL​端点

App Builder资源到产品URL端点

此端点检索与给定资产关联的SKU列表：

使用示例

const { Core } = require('@adobe/aio-sdk')

async function main(params) {

    // Build your own matching logic here to return the products that map to the assetId
    // var productMatches = [];
    // params.assetId
    // params.eventData.assetMetadata['commerce:isCommerce']
    // params.eventData.assetMetadata['commerce:skus'][i]
    // params.eventData.assetMetadata['commerce:roles']
    // params.eventData.assetMetadata['commerce:positions'][i]
    // ...
    // End of your matching logic

    // Set skip to true if the mapping hasn't changed
    const skipSync = false;

    return {
        statusCode: 200,
        body: {
            asset_id: params.assetId,
            product_matches: [
                {
                    product_sku: "<YOUR-SKU-HERE>",
                    asset_roles: ["thumbnail", "image", "swatch_image", "small_image"],
                    asset_position: 1
                }
            ],
            skip: skipSync
        }
    };
}

exports.main = main;

请求

POST https://your-app-builder-url/api/v1/web/app-builder-external-rule/asset-to-product
参数
数据类型
描述
assetId
字符串
表示更新的资产ID。
eventData
对象
与资源关联的事件有效负载（例如，匹配程序从eventData.assetMetadata中读取的资源元数据）。

响应

{
  "asset_id": "{ASSET_ID}",
  "product_matches": [
    {
      "product_sku": "{PRODUCT_SKU_1}",
      "asset_roles": ["thumbnail", "image"]
    },
    {
      "product_sku": "{PRODUCT_SKU_2}",
      "asset_roles": ["thumbnail"]
    }
  ],
  "skip": false
}
参数
数据类型
描述
asset_id
字符串
匹配的资产ID。
product_matches
数组
与资产关联的产品列表。
skip
布尔型
（可选）当true时，规则引擎将跳过此资产的同步（无产品映射更新）。 如果省略false，则运行正常处理。 请参阅跳过同步处理。

App Builder产品到资源URL端点

此端点检索与给定SKU关联的资源列表：

使用示例

const { Core } = require('@adobe/aio-sdk')

async function main(params) {
    // return asset matches for a product
    // Build your own matching logic here to return the assets that map to the productSku
    // var assetMatches = [];
    // params.productSku
    // ...
    // End of your matching logic

    // Set skip to true if the mapping hasn't changed
    const skipSync = false;

    return {
        statusCode: 200,
        body: {
            product_sku: params.productSku,
            asset_matches: [
                {
                    asset_id: "<YOUR-ASSET-ID-HERE>", // urn:aaid:aem:1aa1d5i2-17h8-40a7-a228-e3ur588deee1
                    asset_roles: ["thumbnail", "image", "swatch_image", "small_image"],
                    asset_format: "image", // can be "image" or "video"
                    asset_position: 1
                }
            ],
            skip: skipSync
        }
    };
}

exports.main = main;

请求

POST https://your-app-builder-url/api/v1/web/app-builder-external-rule/product-to-asset
参数
数据类型
描述
productSku
字符串
表示更新的产品SKU。
eventData
对象
与产品关联的事件有效负载（例如，匹配器从传入事件使用的字段）。

响应

{
  "product_sku": "{PRODUCT_SKU}",
  "asset_matches": [
    {
      "asset_id": "{ASSET_ID_1}",
      "asset_roles": ["thumbnail", "image"],
      "asset_position": 1,
      "asset_format": "image"
    },
    {
      "asset_id": "{ASSET_ID_2}",
      "asset_roles": ["thumbnail"],
      "asset_position": 2,
      "asset_format": "image"
    }
  ],
  "skip": false
}
参数
数据类型
描述
product_sku
字符串
匹配的产品SKU。
asset_matches
数组
与产品关联的资产列表。
skip
布尔型
（可选）当true时，规则引擎将跳过对此产品的同步（无资产映射更新）。 如果省略false，则运行正常处理。 请参阅跳过同步处理。

asset_matches参数包含以下属性：

属性
数据类型
描述
asset_id
字符串
资产ID。
asset_roles
数组
资产角色。 使用支持的Commerce资源角色，如thumbnail、image、small_image和swatch_image。 使用AEM Assets集成扩展1.4.6及更高版本时，也可以使用自定义图像角色（如hero或custom_role_1）。
asset_format
字符串
资源格式。 可能的值为image和video。
asset_position
数字
资产在产品库中的位置。

跳过同步处理

skip参数允许自定义匹配程序绕过特定资产或产品的同步处理。

当您的App Builder应用程序在响应中返回"skip": true时，规则引擎不会向Commerce发送该资产或产品的更新或删除API请求。 此优化可减少不必要的API调用并提高性能。

recommendation-more-help
commerce-help-aem-assets-integration