REST API：上传文件

🌐 REST API: Upload files

媒体库功能在 Strapi 的后端服务器中由 upload 包提供支持。要向 Strapi 上传文件，你可以直接从管理面板使用媒体库，也可以使用 REST API，可用的端点如下：

🌐 The Media Library feature is powered in the back-end server of Strapi by the upload package. To upload files to Strapi, you can either use the Media Library directly from the admin panel, or use the REST API, with the following available endpoints : | 方法 | 路径 | 描述 || :----- | :---------------------- | :------------------ || GET | /api/upload/files | 获取文件列表 || GET | /api/upload/files/:id | 获取特定文件 || POST | /api/upload | 上传文件 || POST | /api/upload?id=x | 更新文件信息 || DELETE | /api/upload/files/:id | 删除文件 |

Notes

文件夹是仅限管理员面板的功能，不属于内容 API（REST 或 GraphQL）。通过 REST 上传的文件位于自动创建的“API 上传”文件夹中。
GraphQL API 不支持上传媒体文件。要上传文件，请使用 REST API 或直接从管理面板的媒体库添加文件。一些用于更新或删除已上传媒体文件的 GraphQL 变更仍然可能（详情请参见 GraphQL API 文档）。

上传文件

🌐 Upload files

将一个或多个文件上传到你的应用。

🌐 Upload one or more files to your application.

files 是唯一接受的参数，用于描述要上传的文件。其值可以是 Buffer 或 Stream。

Tip

上传图片时，包含一个 fileInfo 对象以设置文件名、替代文本和标题。

🌐 When uploading an image, include a fileInfo object to set the file name, alt text, and caption.

Browser
Node.js

<form>
  
  <input type="file" name="files" />
  <input
    type="hidden"
    name="fileInfo"
    value='{"name":"homepage-hero","alternativeText":"Person smiling while
      holding laptop","caption":"Hero image used on the homepage"}'
  />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  const form = document.querySelector('form');

  form.addEventListener('submit', async (e) => {
    e.preventDefault();

    await fetch('/api/upload', {
      method: 'post',
      body: new FormData(e.target)
    });
  });
</script>

import { FormData } from 'formdata-node';
import fetch, { blobFrom } from 'node-fetch';

const file = await blobFrom('./1.png', 'image/png');
const form = new FormData();

form.append('files', file, "1.png");
form.append(
  'fileInfo',
  JSON.stringify({
    name: 'Homepage hero',
    alternativeText: 'Person smiling while holding laptop',
    caption: 'Hero image used on the homepage',
  })
);

const response = await fetch('http://localhost:1337/api/upload', {
  method: 'post',
  body: form,
});

Caution

你必须在请求正文中发送 FormData。

🌐 You have to send FormData in your request body.

上传入口文件

🌐 Upload entry files

上传一个或多个将链接到特定条目的文件。

🌐 Upload one or more files that will be linked to a specific entry.

接受以下参数：

🌐 The following parameters are accepted: | 参数 | 描述 || --- | --- ||files | 要上传的文件。值可以是 Buffer 或 Stream。 ||path (可选) | 文件将上传到的文件夹（仅在 strapi-provider-upload-aws-s3 上支持）。 || refId | 将与文件关联的条目 ID。 || ref | 文件将关联的模型的唯一 ID（uid）（详见下文）。 || source (可选) | 模型所在插件的名称。 || field | 文件将精确关联到的条目字段。 |

例如，给定 Restaurant 模型属性：

🌐 For example, given the Restaurant model attributes:

/src/api/restaurant/content-types/restaurant/schema.json
{
  // ...
  "attributes": {
    "name": {
      "type": "string"
    },
    "cover": {
      "type": "media",
      "multiple": false,
    }
  }
// ...
}

以下是相应前端的示例代码：

🌐 The following is an example of a corresponding front-end code:

<form>
  
  <input type="file" name="files" />
  <input type="text" name="ref" value="api::restaurant.restaurant" />
  <input type="text" name="refId" value="5c126648c7415f0c0ef1bccd" />
  <input type="text" name="field" value="cover" />
  <input type="submit" value="Submit" />
</form>

<script type="text/javascript">
  const form = document.querySelector('form');

  form.addEventListener('submit', async (e) => {
    e.preventDefault();

    await fetch('/api/upload', {
      method: 'post',
      body: new FormData(e.target)
    });
  });
</script>

Caution

你必须在请求正文中发送 FormData。

🌐 You have to send FormData in your request body.

更新文件信息

🌐 Update fileInfo

更新应用中的文件。

🌐 Update a file in your application.

fileInfo 是唯一被接受的参数，用于描述要更新的文件信息：

import { FormData } from 'formdata-node';
import fetch from 'node-fetch';

const fileId = 50;
const newFileData = {
  alternativeText: 'My new alternative text for this image!',
};

const form = new FormData();

form.append('fileInfo', JSON.stringify(newFileData));

const response = await fetch(`http://localhost:1337/api/upload?id=${fileId}`, {
  method: 'post',
  body: form,
});

模型定义

🌐 Models definition

向模型（或另一个插件的模型）添加文件属性就像添加一个新的关联。

🌐 Adding a file attribute to a model (or the model of another plugin) is like adding a new association.

以下示例允许你上传并附加一个文件到 avatar 属性：

🌐 The following example lets you upload and attach one file to the avatar attribute:

/src/api/restaurant/content-types/restaurant/schema.json

{
  // ...
  {
    "attributes": {
      "pseudo": {
        "type": "string",
        "required": true
      },
      "email": {
        "type": "email",
        "required": true,
        "unique": true
      },
      "avatar": {
        "type": "media",
        "multiple": false,
      }
    }
  }
  // ...
}

以下示例允许你上传并附加多张图片到 restaurant 内容类型：

🌐 The following example lets you upload and attach multiple pictures to the restaurant content-type:

/src/api/restaurant/content-types/restaurant/schema.json
{
  // ...
  {
    "attributes": {
      "name": {
        "type": "string",
        "required": true
      },
      "covers": {
        "type": "media",
        "multiple": true,
      }
    }
  }
  // ...
}

上传文件​

上传入口文件​

更新文件信息​

模型定义​

上传文件

上传入口文件

更新文件信息

模型定义