Use media in OSDK applications（在 OSDK 应用中使用媒体(Media)）¶

:::callout{theme="warning"} Media support in the TypeScript OSDK is in beta and subject to change during development. To enable media support, navigate to SDK versions from the left side panel of Developer Console, then select Settings to open the Package settings page. From here, toggle on TypeScript beta features. :::

This page describes how to read, upload, and use media in your Ontology SDK applications. Object types and Actions with media references can be included in your Ontology SDK application for reading and writing media items.

You can also use Developer Console to generate documentation specific to your Ontology, including media reference properties on your object types.

Read media reference properties¶

Fetch metadata and contents of your media reference property by calling fetchMetadata() and fetchContents() on the media reference property.

import { OsdkMediaObject } from "@my-media-osdk/sdk";
import { MediaMetadata, MediaReference } from "@osdk/api";
import { Osdk, Result } from "@osdk/client";

const result = await client(OsdkMediaObject).fetchOne("<primaryKey>");

// Fetch metadata of a media property
const mediaMetadata = await result.mediaReference?.fetchMetadata();

// Fetch contents of a media property
const response = await result.mediaReference?.fetchContents();

if (response.ok) {
    const data = await response.blob();
    // ...
}

Upload media to the Ontology¶

Use uploadMedia to upload media to the Ontology within an Ontology edit function. This returns a MediaReference that you can use to set a media property on an object.

For more details on using media in functions, including TypeScript v1 support, see media in functions.

```typescript tab="TypeScript v2" // Ensure you are using TypeScript OSDK 2.6 or greater to use media uploads // in Ontology Edit Functions.

import type { Client } from "@osdk/client"; import { Aircraft } from "@ontology-sdk/sdk"; import type { Edits } from "@osdk/functions"; import { createEditBatch, uploadMedia } from "@osdk/functions";

async function uploadTextToNewPlane(client: Client): Promise[]> { const batch = createEditBatch>(client); const blob = new Blob(["Hello, world"], { type: "text/plain" }); const mediaReference = await uploadMedia( client, { data: blob, fileName: "/planes/aircraft.txt" } ); batch.create(Aircraft, { myMediaProperty: mediaReference, / ... / }); return batch.getEdits(); }

export default uploadTextToNewPlane;

```python tab="Python"
# Ensure you are using Python OSDK 2.145 or greater to use media uploads
# in Ontology Edit Functions.

from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft
from functions.api import function, OntologyEdit

@function(beta=True, edits=[Aircraft])
def upload_text_to_new_plane() -> list[OntologyEdit]:
    client = FoundryClient()
    edits = client.ontology.edits()
    media_reference = client.ontology.media.upload_media(
        body="Hello, world".encode("utf8"),
        filename="/planes/aircraft.txt",
    )
    edits.objects.Aircraft.create(
        pk = "primary_key",
        my_media_property=media_reference,
        # ...
    )
    return edits.get_edits()

Use uploaded media in Actions¶

Once you have uploaded media to the Ontology, you can pass the returned MediaReference to an Action that accepts media as a parameter.

import { createMediaObject } from "@my-media-osdk/sdk";
import { MediaReference } from "@osdk/api";

const mediaReference: MediaReference = await uploadMedia();
const result = await client(createMediaObject).applyAction(
    {
      "media_reference": mediaReference,
      "path": "value"
    },
    {
      $returnEdits: true,
    }
);

Considerations¶

Backing an object property with multiple media sets is not supported in OSDK applications. You will receive an error if you attempt to read or write to an object property that is backed by multiple media sets.
Media reference lists are not supported as a property type in OSDK applications.

中文翻译¶

在 OSDK 应用中使用媒体(Media)¶

:::callout{theme="warning"} TypeScript OSDK 中的媒体支持目前处于测试阶段，在开发过程中可能会有所变更。要启用媒体支持，请从开发者控制台(Developer Console)左侧面板导航至 SDK 版本(SDK versions)，然后选择 设置(Settings) 打开 包设置(Package settings) 页面。在此处，开启 TypeScript 测试版功能。 :::

本页面介绍如何在本体论 SDK(Ontology SDK)应用中读取、上传和使用媒体。包含媒体引用(Media Reference)的对象类型和操作(Actions)可以纳入您的本体论 SDK 应用中，用于读取和写入媒体项目。

您还可以使用开发者控制台(Developer Console)为您的本体论生成文档，包括对象类型上的媒体引用属性。

读取媒体引用属性(Media Reference Properties)¶

通过调用媒体引用属性上的 fetchMetadata() 和 fetchContents() 方法，获取媒体引用属性的元数据和内容。

import { OsdkMediaObject } from "@my-media-osdk/sdk";
import { MediaMetadata, MediaReference } from "@osdk/api";
import { Osdk, Result } from "@osdk/client";

const result = await client(OsdkMediaObject).fetchOne("<primaryKey>");

// 获取媒体属性的元数据
const mediaMetadata = await result.mediaReference?.fetchMetadata();

// 获取媒体属性的内容
const response = await result.mediaReference?.fetchContents();

if (response.ok) {
    const data = await response.blob();
    // ...
}

上传媒体到本体论(Ontology)¶

在本体论编辑函数(Ontology Edit Function)中使用 uploadMedia 将媒体上传到本体论。该函数返回一个 MediaReference，可用于设置对象上的媒体属性。

有关在函数中使用媒体的更多详细信息，包括 TypeScript v1 支持，请参阅函数中的媒体。

```typescript tab="TypeScript v2" // 请确保使用 TypeScript OSDK 2.6 或更高版本以在本体论编辑函数中使用媒体上传功能。

import type { Client } from "@osdk/client"; import { Aircraft } from "@ontology-sdk/sdk"; import type { Edits } from "@osdk/functions"; import { createEditBatch, uploadMedia } from "@osdk/functions";

async function uploadTextToNewPlane(client: Client): Promise[]> { const batch = createEditBatch>(client); const blob = new Blob(["Hello, world"], { type: "text/plain" }); const mediaReference = await uploadMedia( client, { data: blob, fileName: "/planes/aircraft.txt" } ); batch.create(Aircraft, { myMediaProperty: mediaReference, / ... / }); return batch.getEdits(); }

export default uploadTextToNewPlane;

```python tab="Python"
# 请确保使用 Python OSDK 2.145 或更高版本以在本体论编辑函数中使用媒体上传功能。

from ontology_sdk import FoundryClient
from ontology_sdk.ontology.objects import Aircraft
from functions.api import function, OntologyEdit

@function(beta=True, edits=[Aircraft])
def upload_text_to_new_plane() -> list[OntologyEdit]:
    client = FoundryClient()
    edits = client.ontology.edits()
    media_reference = client.ontology.media.upload_media(
        body="Hello, world".encode("utf8"),
        filename="/planes/aircraft.txt",
    )
    edits.objects.Aircraft.create(
        pk = "primary_key",
        my_media_property=media_reference,
        # ...
    )
    return edits.get_edits()

在操作(Actions)中使用已上传的媒体¶

将媒体上传到本体论后，您可以将返回的 MediaReference 传递给接受媒体作为参数的操作(Action)。

import { createMediaObject } from "@my-media-osdk/sdk";
import { MediaReference } from "@osdk/api";

const mediaReference: MediaReference = await uploadMedia();
const result = await client(createMediaObject).applyAction(
    {
      "media_reference": mediaReference,
      "path": "value"
    },
    {
      $returnEdits: true,
    }
);

注意事项(Considerations)¶

OSDK 应用不支持将对象属性关联多个媒体集(Media Sets)。如果您尝试读取或写入关联了多个媒体集的对象属性，将会收到错误提示。
OSDK 应用不支持将媒体引用列表(Media Reference Lists)作为属性类型。