Attachments（附件（Attachments））¶
:::callout{theme="warning"} TypeScript v1 functions are executed in an environment that has strict memory limits. Exceeding these memory limits can happen quickly when dealing with file data; we recommend only interacting with attachments under 20MB. Python and TypeScript v2 functions have a default limit of 1GB, which can be adjusted in Ontology Manager. :::
An attachment is a file that acts like an object property. Attachments are uploaded as temporary files and attached to objects using actions. Once attached to an object, an attachment is persisted and can be accessed similarly to other properties.
Attachments in functions¶
Attachments can be passed into functions as inputs from actions, or accessed as properties on objects. You can also create and return attachments in functions.
When using Python, attachments are managed using the API Gateway. An attachment type is provided in the Python OSDK.
Below is the import syntax for attachments by language:
```typescript tab="TypeScript v1" import { Attachment } from "@foundry/functions-api";
```typescript tab="TypeScript v2"
import { Attachment } from "@osdk/functions";
```python tab="Python"
For convenience, the OSDK Attachment type is re-exported from the Python functions functions.api package.¶
from functions.api import Attachment
## Read attachment data
A read method is provided on attachments to read their raw data. The signature for the method is as follows:
```typescript tab="TypeScript v1"
// Blob is a standard JavaScript type, representing a file-like object of immutable, raw data.
// https://developer.mozilla.org/en-US/docs/Web/API/Blob
readAsync(): Promise<Blob>;
``typescript tab="TypeScript v2"
// Response interface is part of the Fetch API, and is provided byundici` in the TypeScript v2 environment.
// https://developer.mozilla.org/en-US/docs/Web/API/Response
fetchContents(): Promise```python tab="Python"
# BytesIO is a standard Python type, representing a binary stream.
# https://docs.python.org/3/library/io.html#io.BytesIO
def read(self) -> BytesIO: ...
You may need to use libraries or write your own custom code for handling complex file types. For example, PDFs must be parsed with an appropriate library. Learn more about adding dependencies to functions repositories.
File parsing in TypeScript v1¶
TypeScript v1 functions do not offer filesystem support. Often, dependencies related to parsing file data will rely on the fs module, which is not available in the functions environment. This restriction may cause fs module errors during compilation and execution. To work around this restriction, you can introduce a dependency on an in-memory file system (memfs, for example). Then, alias the dependency under the fs name.
Below is an example using the NPM dependency memfs in a package.json file:
"fs": "npm:memfs@^x.x.x"
Create attachments¶
Functions can also be used to create attachments and attach them to objects. For attachments created in functions to be persisted, the function must make an Ontology edit that links the attachment to an object.
:::callout{theme="warning"}
Attachments that are not attached to an object can only be viewed by the uploader and are automatically deleted after a certain period of time.
TypeScript v2 functions do not support creating attachments.
:::
To create an attachment, use an upload function on the attachment. The signature for the upload function by language is as follows:
```typescript tab="TypeScript v1" import { Attachments, Attachment } from "@foundry/functions-api";
// On Attachments:
uploadFile(filename: string, blob: Blob): Promise```python tab="Python"
from ontology_sdk import FoundryClient
from foundry_sdk_runtime.attachments import AttachmentMetadata
# On FoundryClient:
def upload(file_path: str, attachment_name: str) -> AttachmentMetadata: ...
# `file_path` is a local file to be uploaded.
The following example shows the process for uploading a file and assigning the resulting attachment to an object.
```typescript tab="TypeScript v1" import { Attachments, Attachment, OntologyEditFunction } from "@foundry/functions-api";
@OntologyEditFunction()
public async updateMaintenanceLog(aircraft: Aircraft): Promise
// You will likely need to rely on libraries or custom code to create the `Blob` object, which is
// passed as a parameter into the `uploadFile` method.
// Compare the current aircraft logs and completed logs and create a new maintenance log.
const updatedMaintenanceLogData: Blob;
aircraft.maintenanceLog = await Attachments.uploadFile("maintenance-log.txt", updatedMaintenanceLogData);
}
python tab="Python"
from io import BytesIO
from functions.api import function, Attachment, OntologyEdit
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft
@functions(edits=[Aircraft])
def update_maintenance_log(
aircraft: Aircraft,
completed_maintenance_log: Attachment
) -> list[OntologyEdit]:
client = FoundryClient()
ontology_edits = client.ontology.edits()
maintenance_log_data: BytesIO = aircraft.maintenance_log.read()
completed_maintenance_log_data: BytesIO = completed_maintenance_log.read()
# Compare the current aircraft logs and completed logs and create a new maintenance log
updated_maintenance_log_data: BytesIO = get_updated_maintenance_log(
maintenance_log_data,
completed_maintenance_log_data
)
editable_aircraft = ontology_edits.objects.Aircraft.edit(aircraft)
with open("updated-maintenance-log.txt", "wb") as f:
f.write(updated_maintenance_log_data.getbuffer())
editable_aircraft.maintenance_log = client.ontology.attachments.upload(
"updated-maintenance-log.txt",
"my_attachment"
)
return ontology_edits.get_edits()
```
中文翻译¶
附件（Attachments）¶
:::callout{theme="warning"} TypeScript v1 函数在具有严格内存限制的环境中执行。处理文件数据时，很容易超出这些内存限制；我们建议仅处理 20MB 以下的附件。Python 和 TypeScript v2 函数的默认限制为 1GB，可在 Ontology Manager 中进行调整。 :::
附件（Attachment）是一种类似于对象属性（object property）的文件。附件以临时文件形式上传，并通过操作（actions）附加到对象上。一旦附加到对象，附件便会持久化保存，并可以像其他属性一样被访问。
函数中的附件¶
附件可以作为操作的输入传递给函数，也可以作为对象的属性进行访问。您还可以在函数中创建和返回附件。
使用 Python 时，附件通过 API Gateway 进行管理。Python OSDK 中提供了附件类型。
以下是按语言划分的附件导入语法：
```typescript tab="TypeScript v1" import { Attachment } from "@foundry/functions-api";
```typescript tab="TypeScript v2"
import { Attachment } from "@osdk/functions";
```python tab="Python"
为方便起见，OSDK Attachment 类型从 Python functions 的 functions.api 包中重新导出。¶
from functions.api import Attachment
## 读取附件数据
附件提供了一个读取方法，用于读取其原始数据。该方法的签名如下：
```typescript tab="TypeScript v1"
// Blob 是标准 JavaScript 类型，表示一个类似文件对象的不可变原始数据。
// https://developer.mozilla.org/en-US/docs/Web/API/Blob
readAsync(): Promise<Blob>;
``typescript tab="TypeScript v2"
// Response 接口是 Fetch API 的一部分，在 TypeScript v2 环境中由undici` 提供。
// https://developer.mozilla.org/en-US/docs/Web/API/Response
fetchContents(): Promise```python tab="Python"
# BytesIO 是标准 Python 类型，表示一个二进制流。
// https://docs.python.org/3/library/io.html#io.BytesIO
def read(self) -> BytesIO: ...
您可能需要使用库或编写自定义代码来处理复杂的文件类型。例如，PDF 必须使用适当的库进行解析。了解有关向函数仓库添加依赖项的更多信息。
TypeScript v1 中的文件解析¶
TypeScript v1 函数不支持文件系统。通常，与解析文件数据相关的依赖项会依赖 fs 模块，而该模块在函数环境中不可用。此限制可能导致在编译和执行期间出现 fs 模块错误。要解决此限制，您可以引入对内存文件系统（例如 memfs）的依赖项。然后，将该依赖项别名为 fs 名称。
以下是在 package.json 文件中使用 NPM 依赖项 memfs 的示例：
"fs": "npm:memfs@^x.x.x"
创建附件¶
函数也可用于创建附件并将其附加到对象。要使函数中创建的附件持久化，该函数必须执行一个本体编辑（Ontology edit），将附件链接到对象。
:::callout{theme="warning"}
未附加到对象的附件只能由上传者查看，并且会在一定时间后自动删除。
TypeScript v2 函数不支持创建附件。
:::
要创建附件，请使用附件上的上传函数。按语言划分的上传函数签名如下：
```typescript tab="TypeScript v1" import { Attachments, Attachment } from "@foundry/functions-api";
// 在 Attachments 上：
uploadFile(filename: string, blob: Blob): Promise```python tab="Python"
from ontology_sdk import FoundryClient
from foundry_sdk_runtime.attachments import AttachmentMetadata
# 在 FoundryClient 上：
def upload(file_path: str, attachment_name: str) -> AttachmentMetadata: ...
# `file_path` 是要上传的本地文件。
以下示例展示了上传文件并将生成的附件分配给对象的过程。
```typescript tab="TypeScript v1" import { Attachments, Attachment, OntologyEditFunction } from "@foundry/functions-api";
@OntologyEditFunction()
public async updateMaintenanceLog(aircraft: Aircraft): Promise
// 您可能需要依赖库或自定义代码来创建 `Blob` 对象，该对象将作为参数传递给 `uploadFile` 方法。
// 比较当前的飞机日志和已完成日志，并创建新的维护日志。
const updatedMaintenanceLogData: Blob;
aircraft.maintenanceLog = await Attachments.uploadFile("maintenance-log.txt", updatedMaintenanceLogData);
}
python tab="Python"
from io import BytesIO
from functions.api import function, Attachment, OntologyEdit
from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft
@functions(edits=[Aircraft])
def update_maintenance_log(
aircraft: Aircraft,
completed_maintenance_log: Attachment
) -> list[OntologyEdit]:
client = FoundryClient()
ontology_edits = client.ontology.edits()
maintenance_log_data: BytesIO = aircraft.maintenance_log.read()
completed_maintenance_log_data: BytesIO = completed_maintenance_log.read()
# 比较当前的飞机日志和已完成日志，并创建新的维护日志
updated_maintenance_log_data: BytesIO = get_updated_maintenance_log(
maintenance_log_data,
completed_maintenance_log_data
)
editable_aircraft = ontology_edits.objects.Aircraft.edit(aircraft)
with open("updated-maintenance-log.txt", "wb") as f:
f.write(updated_maintenance_log_data.getbuffer())
editable_aircraft.maintenance_log = client.ontology.attachments.upload(
"updated-maintenance-log.txt",
"my_attachment"
)
return ontology_edits.get_edits()
```