文档Adobe Commerce的Data Connection扩展

添加自定义订单属性

Last update: Fri Feb 21 2025 00:00:00 GMT+0000 (Coordinated Universal Time)
  • 主题：

创建对象：

  • 管理员
  • 开发人员

在本文中，您将了解如何向后台事件添加自定义属性。 通过自定义属性，您可以捕获丰富的数据见解以增强分析并进而为购物者创建个性化体验。

自定义属性可在两个级别受支持：

  • 订单级别
  • 订单物料级别
NOTE
Adobe Commerce支持数据类型为字符串、布尔值或日期的自定义属性。

将自定义属性添加到Back Office事件要求您：

  1. 在Commerce安装中创建项目。
  2. 更新您的架构，以便将新的自定义属性正确引入Experience Platform。
  3. 在管理员中，确认正在捕获自定义属性并将其发送到Experience Platform。
IMPORTANT
下面的目录结构和代码示例说明了如何实施自定义属性。 所需的实际目录结构和代码取决于存储配置和环境。

步骤1：创建目录结构

  1. 导航到Commerce安装中的app/code目录并创建模块目录。 例如： Magento/AepCustomAttributes。 此目录包含自定义属性所需的文件。
  2. 在模块目录中，创建一个名为etc的子目录。 etc目录包含module.xml、query.xml、di.xml和et_schema.xml文件。

步骤2：定义依赖项和设置版本

创建定义依赖项和安装版本的module.xml文件。 例如：

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:Module/etc/module.xsd">
    <module name="Magento_AepCustomAttributes">
        <sequence>
            <module name="Magento_SalesOrderDataExporter"/>
        </sequence>
    </module>
</config>

步骤3：检索销售订单数据

创建检索销售订单数据的query.xml文件。 例如：

<?xml version="1.0"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:Module:Magento_QueryXml:etc/query.xsd">
  <query name="salesOrdersV2">
    <source name="sales_order">
      <link-source name="sales_order_inventory_source" link-type="inner">
        <attribute name="inventory_source_code" alias="inventory_source" />
        <using glue="and">
          <condition attribute="order_id" operator="eq" type="identifier">entity_id</condition>
         </using>
        </link-source>
    </source>
  </query>
  </config>

步骤4：设置依赖项注入

创建用于设置依赖项注入的di.xml文件。 例如：

  <?xml version="1.0"?>
  <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:framework:ObjectManager/etc/config.xsd">
      <type name="Magento\AepCustomAttributes\Model\Provider\CustomAttribute">
          <arguments>
              <argument name="usingField" xsi:type="string">commerceOrderId</argument>
          </arguments>
      </type>
      <type name="Magento\AepCustomAttributes\Model\Provider\OrderItemCustomAttribute">
          <arguments>
              <argument name="usingField" xsi:type="string">entityId</argument>
          </arguments>
      </type>
      <type name="Magento\DataServices\Model\ProductContext">
          <plugin name="product-context-plugin" type="Magento\AepCustomAttributes\Plugin\Model\ProductContext"/>
      </type>
  </config>

步骤5：定义用于依赖项注入的服务

创建一个et_schema.xml文件，该文件定义用于依赖项注入的服务。 例如：

  <?xml version="1.0"?>
  <config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="urn:magento:module:Magento_DataExporter:etc/et_schema.xsd">
      <record name="OrderV2">
          <field name="additionalInformation" type="CustomAttribute" repeated="true" provider="Magento\AepCustomAttributes\Model\Provider\CustomAttribute">
              <using field="commerceOrderId"/>
          </field>
      </record>
      <record name="OrderItemV2">
          <field name="additionalInformation" type="CustomAttribute" repeated="true" provider="Magento\AepCustomAttributes\Model\Provider\OrderItemCustomAttribute">
              <using field="entityId"/>
          </field>
      </record>
  </config>

步骤6：为PHP文件创建目录

在与etc目录相同的级别，创建一个名为Module/Provider的目录。 此目录包含OrderCustomAttributes和OrderItemCustomAttributes PHP文件。

步骤7：定义OrderCustomAttributes

创建定义顺序自定义属性的OrderCustomAttributes.php文件。 例如：

declare(strict_types=1);

namespace Magento\AepCustomAttributes\Model\Provider;

use Magento\Framework\Serialize\Serializer\Json;

class CustomAttribute
{
  /**
   * @var Json
   */
  private Json $jsonSerializer;

  /**
   * @var string
   */
  private string $usingField = '';

  /**
   * @param string $usingField
   * @param Json $jsonSerializer
   */
  public function __construct(
      string $usingField,
      Json $jsonSerializer
  ) {
      $this->usingField = $usingField;
      $this->jsonSerializer = $jsonSerializer;
  }

  /**
   * @param array $values
   * @return array
   */
  public function get(array $values): array
  {
      $output = [];

      /**
       * Entity IDs
       */
      $ids = array_column($values, $this->usingField);

      foreach ($this->flatten($values) as $row) {
          $info = \is_string($row['additionalInformation']) ? $row['additionalInformation'] : '{}';
          $unserializedData = $this->jsonSerializer->unserialize($info) ?? [];

          if (isset($row)) {
              $unserializedData['order_channel'] = 'order_channel';
              $unserializedData['order_status'] = 'order_status';

              $additionalInformation = [];
              foreach ($unserializedData as $name => $value) {
                  $additionalInformation[] = [
                      'name' => $name,
                      'value' => \is_string($value) ? $value : $this->jsonSerializer->serialize($value)
                  ];
              }
              foreach ($additionalInformation as $information) {
                  $output[] = [
                      'additionalInformation' => $information,
                      $this->usingField => $row[$this->usingField],
                  ];
              }
          }
      }
      return $output;
  }

  /**
   * @param $values
   * @return array
   */
  private function flatten($values): array
  {
      if (isset(current($values)[0])) {
          return array_merge([], ...array_values($values));
      }
      return $values;
  }
}

步骤8：定义OrderItemCustomAttributes

创建定义订单项自定义属性的OrderItemCustomAttributes.php文件。 例如：

declare(strict_types=1);

namespace Magento\AepCustomAttributes\Model\Provider;

use Magento\Framework\Serialize\Serializer\Json;

class OrderItemCustomAttribute
{
  /**
   * @var Json
   */
  private Json $jsonSerializer;

  /**
   * @var string
   */
  private string $usingField = '';

  /**
   * @param Json $jsonSerializer
   * @param string $usingField
   */
  public function __construct(
      Json $jsonSerializer,
      string $usingField
  ) {
      $this->jsonSerializer = $jsonSerializer;
      $this->usingField = $usingField;
  }

  /**
   * Getting additional attributes data.
   *
   * @param array $values
   * @return array
   */
  public function get(array $values): array
  {
      $output = [];
      $values = $this->flatten($values);

      foreach ($values as $row) {
          $info = \is_string($row['additionalInformation']) ? $row['additionalInformation'] : '{}';
          $unserializedData = $this->jsonSerializer->unserialize($info) ?? [];
          $unserializedData['product_brand'] = implode(',', ['label 1', 'label 2']);

          $additionalInformation = [];
          foreach ($unserializedData as $name => $value) {
              $additionalInformation[] = [
                  'name' => $name,
                  'value' => \is_string($value) ? $value : $this->jsonSerializer->serialize($value)
              ];
          }
          foreach ($additionalInformation as $information) {
              $output[] = [
                  'additionalInformation' => $information,
                  $this->usingField => $row[$this->usingField],
              ];
          }
      }
      return $output;
  }

  /**
   * @param $values
   * @return array
   */
  private function flatten($values): array
  {
      if (isset(current($values)[0])) {
          return array_merge([], ...array_values($values));
      }
      return $values;
  }
}

步骤9：为productContext文件创建目录

在与etc目录相同的级别，创建一个名为Plugin/Module的目录。 此目录包含ProductContext.php文件。

步骤10：定义ProductContext类

创建名为ProductContext.php的文件，该文件定义ProductContext类。 例如：

<?php>
namespace Magento\AepCustomAttributes\Plugin\Model;
use Magento\Catalog\Model\Product;
use Magento\DataServices\Model\ProductContext as Subject;
use Magento\Framework\App\ResourceConnection;

class ProductContext
{
    private ?array $brandCache = [];
    public function __construct(
        private ResourceConnection $resourceConnection ) {
    }

    public function afterGetContextData(Subject $subject, array $result Product $product)
    {
        $brand = $product->getCustomAttribute('cust_attr1');
        if (!empty($brand) && $brand->getValue()) {
            $result['brands'] = ['brand_label_1', 'brand_label_2'];
            }
            return $result;
      }
  }

步骤11：注册模块

在与etc目录相同的级别，创建注册模块的registration.php文件。 例如：

<?php>
declare(strict_types=1);

use \Magento\Framework\Component\ComponentRegistrar;

ComponentRegistrar::register(
    ComponentRegistrar::MODULE,
    'Magento_AepCustomAttributes',
    __DIR__
);

步骤12：扩展现有XDM架构

要确保Experience Platform中的Commerce架构能够摄取新的自定义订单属性，您需要扩展架构以包含这些自定义字段。

要了解如何扩展现有XDM架构以包含这些自定义字段，请参阅Experience Platform文档中的在UI中创建和编辑架构一文。 租户ID字段是动态生成的；但是，字段结构应类似于Experience Platform文档中提供的示例。

IMPORTANT
XDM自定义属性必须与从Commerce发送的属性匹配。

到commerce.order，为订单级别添加字段：

订单级别

到productListItems，为订单项级别添加字段：

订单项级别

步骤12：确认正在捕获数据

查看管理员中的数据自定义选项卡，以确认正在捕获自定义属性数据并将其发送到Experience Platform。

故障排除

如果您在​ Data Customization ​选项卡上看到消息No custom order attributes found.，请确认以下事项：

  1. 您已完成启用Data Connector扩展的先决条件。
  2. 您已配置自定义订单属性。
  3. 至少已生成一个订单事件。
recommendation-more-help
1dd1eb92-da61-46c0-8ff9-3831f21eb23e