Shopware 6.5 Store API如何获取1:1关联的实体扩展数据？

我已定义并注册了一个名为my_category的实体扩展，通过1:1关联方式扩展Category实体，代码如下：

...
public function extendFields(FieldCollection $collection): void
{
    $collection->add(
            (new OneToOneAssociationField(
                    'myCategory',
                    'id',
                    'category_id',
                    MyCategoryDefinition::class
            ))->addFlags(new CascadeDelete())
    );
}

public function getDefinitionClass(): string
{
    return CategoryDefinition::class;
}
...

使用实体仓库对该扩展进行数据的添加和查询均正常。现在我希望通过Store API获取该扩展的字段数据，尝试发送了如下请求：

curl --location --request POST 'https://mysite.tld/store-api/category' \
--header 'sw-access-key: xxx' \
--header 'Content-Type: application/json' \
--data-raw '{   
    "includes": {
        "category": [
            "name",
            "myCategory"
        ]
    }
}'

但并未成功。通过HttpKernel追踪请求可以看到，实体仓库已完整获取到扩展的所有字段数据，但请求响应中并未显示该扩展的数据，响应内容如下：

{
    "elements": [
        {
            "name": "Topseller",
            "apiAlias": "category"
        }
    ],
...
}

请问通过Store API获取1:1关联实体扩展数据的正确方式和写法是什么？（Shopware版本为6.5.4.0）

要在Store API中返回1:1关联的扩展实体数据，需要完成以下两步：

1. 配置扩展实体的API可见性 #

确保你的MyCategoryDefinition类中，为需要返回的字段添加ApiAware标记，同时正确定义实体的apiAlias：

// MyCategoryDefinition.php
class MyCategoryDefinition extends EntityDefinition
{
    // ... 其他核心代码

    public function getApiAlias(): string
    {
        return 'my_category'; // 需与关联字段的命名逻辑保持一致
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new FkField('category_id', 'categoryId', CategoryDefinition::class))->addFlags(new Required()),
            // 为需要通过API返回的字段添加ApiAware标记
            (new StringField('custom_field', 'customField'))->addFlags(new ApiAware()),
            // 其他需要返回的字段同理配置
        ]);
    }
}

2. 调整Store API请求的includes参数 #

在请求的includes中，除了声明Category的关联字段myCategory，还要指定扩展实体my_category需要返回的具体字段：

curl --location --request POST 'https://mysite.tld/store-api/category' \
--header 'sw-access-key: xxx' \
--header 'Content-Type: application/json' \
--data-raw '{   
    "includes": {
        "category": [
            "name",
            "myCategory"
        ],
        "my_category": [
            "id",
            "customField" // 填写你需要返回的MyCategory实体字段
        ]
    }
}'

关键说明 #

• Store API不会自动返回关联实体的所有字段，必须通过includes显式指定，且键名要对应扩展实体的apiAlias。
• 即使仓库层已获取到完整数据，序列化层会根据includes配置和字段的ApiAware标记，决定最终返回的内容。

内容的提问来源于stack exchange，提问作者Benny