访问文件 Accessing Files

REST 和 GraphQL API 文档，用于 Directus 中的文件访问和管理。平台管理的每个文件都被上传到配置的存储适配器，其相关元数据在`directus_files`系统集合中进行跟踪。 任何请求的文件转换都是即时处理的，并且只保存到存储中。

访问文件

您的实际文件原件的位置取决于项目的配置，但您可以使用以下 URL 通过 API 始终如一地访问它们。

html
example.com/assets/<file-id>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4

SEO
您可以在 UUID 之后提供一个可选文件名以针对 SEO 进行优化，例如：

example.com/assets/<file-id>/<filename>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4/directus-logo.png

当使用 ?download 查询参数时，此可选文件名也用于 Content-Disposition 标头。

直接文件访问
虽然您可能 技术上 能够公开您的存储适配器根文件系统并通过那里访问您的原始文件，但建议您始终使用 Directus API。 这是您可以利用文件权限和其他内置功能的唯一方法。

原始文件 原始文件占用了 — 602KB and 1800x1200

下载文件

要下载具有正确文件名的资产，您需要将 ?download 查询参数添加到请求中，并将 download 属性添加到您的锚标记。 这将确保添加适当的 内容处置 标头。 如果没有这个，下载将在 same 域上工作，但是它将文件的“id”作为跨域请求的文件名。

示例

html
<a href="https://your-directus.com/assets/<file-id>?download" target="_blank" download="Your File.pdf">Download</a>

请求缩略图

获取缩略图就像在原始文件的 URL 中添加一个 key 查询参数一样简单。 在 Admin App 中，您可以配置不同的资产预设来控制任何给定图像的输出。 如果请求的缩略图尚不存在，则会动态生成并立即返回。

预设转换

自定义转换

或者，如果您将“存储资产转换”设置为全部，则可以使用以下参数进行更细粒度的控制：

  • fit - 缩略图的 fit 始终保持纵横比，可以是以下任何一种 选项：
    • cover - 通过裁剪/剪裁以适应宽度/高度
    • contain - 根据需要使用“信箱”包含在宽度/高度内
    • inside - 调整到尽可能大，确保尺寸小于或等于请求的宽度和高度
    • outside - 调整大小尽可能小，确保尺寸大于或等于请求的宽度和高度
  • width — 缩略图的宽度(以像素为单位)
  • height — 缩略图的高度(以像素为单位)
  • quality - 缩略图的可选品质(1到100)
  • withoutEnlargement - 禁用图像放大
  • format - 返回缩略图的文件格式。jpg、png、webp、tiff之一

高级转换

为了对文件生成进行更高级的控制，Directus 通过 transforms 查询参数公开了 完整的 sharp API。 此参数接受格式为[Operation, ...arguments]的二维数组。

质量与文件大小

质量参数可以是 0-100 之间的任何整数。 接近“0”的质量具有较小的文件大小，但由于压缩伪影，图像质量也很差。 接近“100”的值具有更大的文件大小，但图像质量更好。 以下是四种可能的质量(200x200 封面)，用于直观地比较压缩和文件大小之间的平衡。

25%50%75%100%
25%
4KB		50%
6KB		75%
8KB		100%
38KB

预设

example.com/assets/<file-id>?key=<key>

自定义

example.com/assets/<file-id>?fit=<fit>&width=<width>&height=<height>&quality=<quality>
example.com/assets/1ac73658-8b62-4dea-b6da-529fbc9d01a4?fit=cover&width=200&height=200&quality=80

高级设置

?transforms=[
 ["blur", 45],
 ["tint", "rgb(255, 0, 0)"],
 ["expand", { "right": 200, "bottom": 150 }]
]

文件对象

id uuid
文件的主键

storage string
用于文件的存储适配器。

filename_disk string
保存在存储适配器上的文件的名称。

filename_download string
下载文件时的首选文件名。

title string
文件的标题。

type string
文件的 MIME 类型。

folder many-to-one
文件所在的(虚拟)文件夹。 多对一到文件夹.

uploaded_by many-to-one
谁上传的文件。多对一到用户.

uploaded_on datetime
什么时候上传的文件。

modified_by many-to-one
谁最后更新了文件。多对一到 用户.

filesize number
文件的大小(以字节为单位)。

width number
如果文件是一个图像/视频，它的宽度，单位(px)。

height number
如果文件是一个图像/视频，它的高度，单位(px)。

duration number
如果文件包含音频/视频，则为持续时间(以毫秒为单位)。

description string
文件的描述。

location string
文件的位置。

tags array
文件的标签。

metadata object
Directus 能够从文件中抓取任何其他元数据。对于图像，这包括 EXIF、IPTC 和 ICC 信息。

json
{
  "id": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb",
  "storage": "local",
  "filename_disk": "4f4b14fa-a43a-46d0-b7ad-90af5919bebb.jpeg",
  "filename_download": "paulo-silva-vSRgXtQuns8-unsplash.jpg",
  "title": "Paulo Silva (via Unsplash)",
  "type": "image/jpeg",
  "folder": null,
  "uploaded_by": "0bc7b36a-9ba9-4ce0-83f0-0a526f354e07",
  "uploaded_on": "2021-02-04T11:37:41-05:00",
  "modified_by": null,
  "modified_on": "2021-02-04T11:37:42-05:00",
  "filesize": 3442252,
  "width": 3456,
  "height": 5184,
  "duration": null,
  "description": null,
  "location": null,
  "tags": ["photo", "pretty"],
  "metadata": {
    "icc": {
      "version": "2.1",
      "intent": "Perceptual",
      "cmm": "lcms",
      "deviceClass": "Monitor",
      "colorSpace": "RGB",
      "connectionSpace": "XYZ",
      "platform": "Apple",
      "creator": "lcms",
      "description": "c2",
      "copyright": ""
    }
  }
}

列出文件

列出 Directus 中存在的所有文件。

查询参数

支持所有全局查询参数。

返回

最多包含 limit file objects 的数组。 如果没有可用的项目，数据将是一个空数组。

REST API

GET /files
SEARCH /files

了解有关搜索的更多信息 ->

GraphQL

POST /graphql/system
graphql
type Query {
 files: [directus_files]
}
示例
graphql
query {
 files {
  id
  filename_disk
 }
}

检索文件

按主键检索单个文件。

查询参数

支持所有全局查询参数。

返回

如果提供了有效的主键，则返回 文件对象。

REST API

GET /files/:id
示例
GET /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

GraphQL

POST /graphql/system
graphql
type Query {
 files_by_id(id: ID!): directus_files
}
示例
graphql
query {
 files_by_id(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d") {
  id
  filename_disk
 }
}

上传一个文件

上传/创建一个新文件。

要上传文件，请使用multipart/form-data作为编码类型。 文件内容必须在名为“文件”的部分中提供。 文件对象 的所有其他属性也可以作为部分提供，除了 filename_disk 和 filename_download。

或者，您可以将 application/json 与 JSON 请求正文结合使用，将元数据关联到存储中已存在的文件。 需要 type 属性来指定该文件的 mimetype。

订单事项
确保 _首先_定义非文件属性。 这可确保文件元数据与正确的文件相关联。

您可以通过重复具有不同内容的有效负载一次上传多个文件，例如：

js
--__X_BOUNDARY__
Content-Disposition: form-data; name="title"

Example
--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="paulo-silva-vSRgXtQuns8-unsplash.jpg"
Content-Type: image/jpeg

// binary data

--__X_BOUNDARY__
Content-Disposition: form-data; name="title"

Another Title
--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="mae-mu-GFhqNX1gE9E-unsplash.jpg"
Content-Type: image/jpeg

// binary data

在 JavaScript 中，这可以使用原生的 FormData 类来实现：

js
import axios from 'axios'

const fileInput = document.querySelector('input[type="file"]')
const formData = new FormData()

formData.append('title', 'My First File')
formData.append('file', fileInput.files[0])

await axios.post('/files', formData)

查询参数

支持所有全局查询参数。

返回值

返回已上传文件的 file object，如果同时上传了多个文件，则返回 file objects 数组。

POST /files

// Request

Content-Type: multipart/form-data; charset=utf-8; boundary=__X_BOUNDARY__
Content-Length: 3442422

--__X_BOUNDARY__
Content-Disposition: form-data; name="file"; filename="paulo-silva-vSRgXtQuns8-unsplash.jpg"
Content-Type: image/jpeg

ÿØÿàJFIFHHÿâICC_PROFILElcmsmntrRGB XYZ Ü)9acspAPPLöÖÓ-lcms
descü^cprt\wtpthbkpt|rXYZgXYZ¤bXYZ¸rTRCÌ@gTRCÌ@bTRCÌ@descc2textIXXYZ öÖÓ-XYZ 3¤XYZ o¢8õXYZ b™·…ÚXYZ $ „¶ÏcurvËÉc’kö?Q4!ñ)2;’FQw]íkpz‰±š|¬i¿}ÓÃé0ÿÿÿۄ

导入文件

从网络导入文件

查询参数

支持所有全局查询参数。

请求正文

url Required
下载文件的 URL。

data
文件对象 的任何属性。

返回值

返回导入文件的 文件对象。

REST API

POST /files/import
示例
json
// POST /files/import

{
  "url": "https://source.unsplash.com/random",
  "data": {
    "title": "Example"
  }
}

GraphQL

POST /graphql/system
graphql
type Mutation {
 import_file(url: String!, data: create_directus_files_input!): directus_files
}
示例
graphql
mutation {
 import_file(url: "https://source.unsplash.com/random", data: { title: "Example" }) {
  id
 }
}

更新文件

更新现有文件，和/或替换它的文件内容。

查询参数

支持所有全局查询参数。

请求正文

您可以提交包含部分 file object 的 JSON 对象来更新文件元数据，或者发送 multipart/form-data 请求来替换磁盘上的文件内容。 有关此 multipart/form-data 请求的结构的更多信息，请参阅 上传文件。

返回

返回更新文件的 文件对象。

REST API

PATCH /files/:id
示例
json
// PATCH /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

{
  "title": "Example"
}

GraphQL

POST /graphql/system
graphql
type Mutation {
 update_files_item(id: ID!, data: update_directus_files_input!): directus_files
}
示例
graphql
mutation {
 update_files_item(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d", data: { title: "Example" }) {
  id
  title
 }
}

更新多个文件

同时更新多个文件。

查询参数

支持所有全局查询参数。

请求正文

keys Required
您要更新的文件的主键数组。

data Required
文件对象 的任何属性。

返回值

返回更新文件的 文件对象。

REST API

PATCH /files
示例
json
// PATCH /files

{
  "keys": ["b6123925-2fc0-4a30-9d86-863eafc0a6e7", "d17c10aa-0bad-4864-9296-84f522c753e5"],
  "data": {
    "tags": ["cities"]
  }
}

GraphQL

POST /graphql/system
graphql
type Mutation {
 update_files_items(ids: [ID!]!, data: update_directus_files!): [directus_files]
}
示例
graphql
mutation {
 update_files_items(
  ids: ["b6123925-2fc0-4a30-9d86-863eafc0a6e7", "d17c10aa-0bad-4864-9296-84f522c753e5"]
  data: { tags: ["cities"] }
 )
}

删除文件

删除现有文件。

破坏性的
这也将从磁盘中删除文件。

查询参数

支持所有全局查询参数。

返回值

返回空值。

REST API

DELETE /files/:id
示例
DELETE /files/0fca80c4-d61c-4404-9fd7-6ba86b64154d

GraphQL

POST /graphql/system
graphql
type Mutation {
 delete_files_item(id: ID!): delete_one
}
graphql
mutation {
 delete_files_item(id: "0fca80c4-d61c-4404-9fd7-6ba86b64154d") {
  id
 }
}

删除多个文件

一次删除多个文件。

破坏性的
这也将从磁盘中删除文件。

请求正文

文件主键数组

返回值

返回空值。

REST API

DELETE /files
示例
json
// DELETE /files

["d17c10aa-0bad-4864-9296-84f522c753e5", "b6123925-2fc0-4a30-9d86-863eafc0a6e7"]

GraphQL

POST /graphql/system
graphql
type Mutation {
 delete_files_items(ids: [ID!]!): delete_many
}
示例
graphql
mutation {
 delete_files_items(ids: ["d17c10aa-0bad-4864-9296-84f522c753e5", "b6123925-2fc0-4a30-9d86-863eafc0a6e7"]) {
  ids
 }
}
上一篇
访问项目 Items
下一篇
JS SDK 开发框架SDK