通过 Shopware 6 添加图像 API

Add images via Shopware 6 API

我有一个 Shopware 6.3 商店,需要使用集成 API.

将图像迁移到它

我应该如何构建媒体上传的正文?我需要将文件放在某个地方还是只传递 link?

我已经通过此处的指南成功地将新产品推送到 Shopware:https://docs.shopware.com/en/shopware-platform-dev-en/admin-api-guide/writing-entities?category=shopware-platform-dev-en/admin-api-guide#creating-entities but I am not sure how to handle media. In this guide it is only explained how to create links between already uploaded media files to products in here https://docs.shopware.com/en/shopware-platform-dev-en/admin-api-guide/writing-entities?category=shopware-platform-dev-en/admin-api-guide#media-handling 但没有关于如何实际推送媒体文件的示例。

我需要的每张图片都有 URL(在数据库中,以及产品 ID 和图片位置)。

实体架构将媒体描述为:

    "media": {
        "name": "media",
        "translatable": [
            "alt",
            "title",
            "customFields"
        ],
        "properties": {
            "id": {
                "type": "string",
                "format": "uuid"
            },
            "userId": {
                "type": "string",
                "format": "uuid"
            },
            "mediaFolderId": {
                "type": "string",
                "format": "uuid"
            },
            "mimeType": {
                "type": "string",
                "readOnly": true
            },
            "fileExtension": {
                "type": "string",
                "readOnly": true
            },
            "uploadedAt": {
                "type": "string",
                "format": "date-time",
                "readOnly": true
            },
            "fileName": {
                "type": "string",
                "readOnly": true
            },
            "fileSize": {
                "type": "integer",
                "format": "int64",
                "readOnly": true
            },
            "metaData": {
                "type": "object",
                "readOnly": true
            },
            "mediaType": {
                "type": "object",
                "readOnly": true
            },
            "alt": {
                "type": "string"
            },
            "title": {
                "type": "string"
            },
            "url": {
                "type": "string"
            },
            "hasFile": {
                "type": "boolean"
            },
            "private": {
                "type": "boolean"
            },
            "customFields": {
                "type": "object"
            },
            "createdAt": {
                "type": "string",
                "format": "date-time",
                "readOnly": true
            },
            "updatedAt": {
                "type": "string",
                "format": "date-time",
                "readOnly": true
            },
            "translated": {
                "type": "object"
            },
            "tags": {
                "type": "array",
                "entity": "tag"
            },
            "thumbnails": {
                "type": "array",
                "entity": "media_thumbnail"
            },
            "user": {
                "type": "object",
                "entity": "user"
            },
            "categories": {
                "type": "array",
                "entity": "category"
            },
            "productManufacturers": {
                "type": "array",
                "entity": "product_manufacturer"
            },
            "productMedia": {
                "type": "array",
                "entity": "product_media"
            },
            "avatarUser": {
                "type": "object",
                "entity": "user"
            },
            "mediaFolder": {
                "type": "object",
                "entity": "media_folder"
            },
            "propertyGroupOptions": {
                "type": "array",
                "entity": "property_group_option"
            },
            "mailTemplateMedia": {
                "type": "array",
                "entity": "mail_template_media"
            },
            "documentBaseConfigs": {
                "type": "array",
                "entity": "document_base_config"
            },
            "shippingMethods": {
                "type": "array",
                "entity": "shipping_method"
            },
            "paymentMethods": {
                "type": "array",
                "entity": "payment_method"
            },
            "productConfiguratorSettings": {
                "type": "array",
                "entity": "product_configurator_setting"
            },
            "orderLineItems": {
                "type": "array",
                "entity": "order_line_item"
            },
            "cmsBlocks": {
                "type": "array",
                "entity": "cms_block"
            },
            "cmsSections": {
                "type": "array",
                "entity": "cms_section"
            },
            "cmsPages": {
                "type": "array",
                "entity": "cms_page"
            },
            "documents": {
                "type": "array",
                "entity": "document"
            }
        }
    },

但不清楚哪些字段是关键的。我是否需要先创建产品媒体文件夹,然后在向媒体端点发出 POST 请求时使用它的 ID?我可以只指定 URL 并让 Shopware 将图像本身下载到一个文件夹或继续指向我使用过的 URL 吗?我需要将图片存放在 Shopware 中。

我从 URL 下载图片并将它们推送到 Shopware 没有问题,但我不确定如何使用 API (有很多图片而且它们需要批量完成)。

一种可能的解决方案:

首先:创建一个新媒体POST/api/{apiVersion}/media?_response=true

第二个:“上传图片”/api/{apiVersion}/_action/media/{mediaId}/upload?extension={extension}&fileName={imgName}&_response=true

可以在此处找到更多信息:https://forum.shopware.com/discussion/comment/278603/#Comment_278603

在 CASE 图像中,产品使用端点 POST /api/{apiVersion}/product-media 并设置 coverId

所有路由的完整列表可通过 OpenAPI 模式获得:[your-domain/localhost]/api/v3/_info/openapi3.json

也可以在创建产品时一次设置所有媒体和cover&coverId。因此,设置乘积Cover和乘积Media

{
"coverId":"3d5ebde8c31243aea9ecebb1cbf7ef7b",
"productNumber":"SW10002","active":true,"name":"Test",
"description":"fasdf",
"media":[{
"productId":"94786d894e864783b546fbf7c60a3640",
"mediaId":"084f6aa36b074130912f476da1770504",
"position":0,
"id":"3d5ebde8c31243aea9ecebb1cbf7ef7b"
},
{
"productId":"94786d894e864783b546fbf7c60a3640",
"mediaId":"4923a2e38a544dc5a7ff3e26a37ab2ae",
"position":1,
"id":"600999c4df8b40a5bead55b75efe688c"
}],
 "id":"94786d894e864783b546fbf7c60a3640"
}

请记住通过检查示例来检查不记名令牌是否有效:

if (JwtToken.ValidTo >= DateTime.Now.ToUniversalTime() - new TimeSpan(0, 5, 0))
{
    return Client.Get(request);
}
else
{
  // refresh the token by new authentication
  IntegrationAuthenticator(this.key, this.secret);
}
return Client.Get(request);

这适用于 Shopware 6.4

作为一般建议,视情况而定。 APIs 自 6.4 以来发生了一些变化,并且在 https://shopware.stoplight.io/docs/admin-api/docs/guides/media-handling.md.

上还有一个官方文档。

但是,我认为有一个现实生活中的例子总是更容易一些。我在我们的生产环境中所做的基本上就是这些步骤。

  1. (可选)检查媒体对象是否存在
  2. 使用端点 GET /media-files/
  3. 创建一个 media-file 对象
  4. 如果存在,则使用新的媒体 ID 参考上传图像。

让我们假设文件名为 yourfilename.jpg。您还需要一个 media-folder-id,它将引用 Shopware 中的图像文件夹。这可以通过 Admin > Content > Media > Product Media.

在 Shopware 中获得

步骤 0

在将图片上传到 Shopware 之前,您想确保该图片不存在,以便您可以跳过它。

This step is optional, as it is not mandatory to create an image. However you want to have some sort of validation mechanism in a production environment.

请求正文

POST api/search/media

这将 运行 对 Shopware-API 的请求和响应。

{
   "filter":[
      {
         "type":"equals",
         "field":"fileName",
         "value":"yourfilename"
      },
      {
         "type":"equals",
         "field":"fileExtension",
         "value":"jpg"
      },
      {
         "type":"equals",
         "field":"mediaFolderId",
         "value":"d798f70b69f047c68810c45744b43d6f"
      }
   ],
   "includes":{
      "media":[
         "id"
      ]
   }
}

步骤 1

新建一个media-file

请求正文

POST api/_action/sync

此请求将在 Shopware 中创建一个新的媒体对象。

  1. media_id 的值必须是任何 UUID。我将使用这个值:94f83a75669647288d4258f670a53e69
  2. customFields 属性 是可选的。我只是用它来保留哈希值的引用,我可以用它来验证更改的值。
  3. 媒体文件夹 ID 的值是您将从 Shopware-Backend 获得的值。

{
    "create-media": {
        "entity": "media",
        "action": "upsert",
        "payload": [
            {
                "id": "{{media_id}}",
                "customFields": {"hash": "{{file.hash}}"},
                "mediaFolderId": "{{mediaFolderId}}"
            }
        ]
    }
}

回应

响应会告诉您一切正常。

{
   "success":true,
   "data":{
      "create-media":{
         "result":[
            {
               "entities":{
                  "media":[
                     "94f83a75669647288d4258f670a53e69"
                  ],
                  "media_translation":[
                     {
                        "mediaId":"94f83a75669647288d4258f670a53e69",
                        "languageId":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
                     }
                  ]
               },
               "errors":[
                  
               ]
            }
         ],
         "extensions":[
            
         ]
      }
   },
   "extensions":[
      
   ]
}

步骤 2

这是我们将图片上传到 Shopware 的步骤。我们将使用内容类型 image/jpg 的变体。但是,具有 URL 属性的负载也可以工作。详见官方文档

请求正文

POST api/_action/media/94f83a75669647288d4258f670a53e69/upload?extension=jpg&fileName=yourfilename

Note that the media-id is part of the URL. And also the filename but without the file-extension JPG!

这个主体非常简单,在我们的例子中没有负载,因为我们使用 Content-Type: "image/jpeg".

的上传

如果您想使用 URL 作为资源,这将是一个有效载荷:

{
  "url": "<url-to-your-image>"
}