> This page is for Camera to Cloud.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://developer.frame.io/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://developer.frame.io/_mcp/server.

# 方法：アセットの整理

## はじめに

このガイドでは、統合からアセットをアップロードする方法およびその制御内容について説明します。 **

## 必要なもの

[C2C の実装：セットアップ](./implementing-c2c-setting-up)ガイドをまだ読んでいない場合は、目を通してから先へ進んでください。

[C2C ハードウェア](./implementing-c2c-authentication-and-authorization-hardware)または [C2C アプリケーション](./implementing-c2c-authentication-and-authorization-c2c-application)の認証および承認ガイドで受け取った `access_token` が必要です。

## アセットのフォルダー構造

デフォルトで、アセットは次のフォルダー構造で作成されます。

`Cloud Devices`／`{YYYY}_{MM}_{DD}`／`{ASSET_TYPE}`／`{YOUR_DEVICE}`／`{ASSET_NAME}`

ここで、`{ASSET_TYPE}` は `VIDEO`、`AUDIO`、`DATA` のいずれか（デバイスモデルのチャネルごとに設定済み）、`{YOUR_DEVICE}` はユーザーのプロジェクトに接続されているプロジェクトデバイスの名前、`{ASSET_NAME}` はアップロードしたアセットの名前で、Frame.io で実際に再生可能なアセットです。

### 拡張子ルーティング

`{ASSET_NAME}` のファイル拡張子に基づき、様々なアセットをカスタム `{ASSET_TYPE}` フォルダーにルーティングするようデバイスを設定できます。例えば、統合に生成される様々なファイルタイプがあり、それぞれが特定の場所に属しているとします。これらのアセットを次のようにマッピングするように指定できます。

```text
.mov -> VIDEO
.mp4 -> VIDEO
.raw -> STILLS
.jpeg -> STILLS
.pdf -> CAMERA REPORTS
.las -> LiDAR Scans
```

次のアセットを作成すると、

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_codes]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "IMAGE_0001.jpeg", 
            "filetype": "image/jpeg", 
            "filesize": 21136250,
            "offset": 10
        }
__JSON__
} | python -m json.tool
```

<Info title="API endpoint specificaton">
Docs for `/v2/assets` can be [found here](https://developer.frame.io/api/reference/operation/deviceAssetCreate/)
</Info>

...次のような場所にルーティングされます。`Cloud Devices`／`2022_04_01`／`STILLS`／`MY_DEVICE`／`IMAGE_0001.jpeg`。

ファイル名が `A001_C001.mov` である場合、次の場所にルーティングされます。`Cloud Devices`／`2022_04_01`／`VIDEO`／`MY_DEVICE`／`A001_C001.mov`。

### トークン化されたアップロードパス

一部の統合では、デバイスが作成するフォルダー構造をより細かく制御したい場合があります。その場合、[Frame.io ](http://frame.io/)では、C2C デバイスから [Frame.io](http://frame.io/) にファイルをアップロードする方法にある程度の一貫性があることを確認する必要があり、特に、C2C デバイスがプロジェクトのどの部分とやり取りできるかについて、[Frame.io](http://frame.io/) のお客様に保証する必要があります。そのため、インテグレーターは `{YOUR_DEVICE}` フォルダー内のアセットのアップロード場所をカスタマイズできますが、そのフォルダー外にアセットをアップロードすることはできません。

カスタムフォルダー構造にアップロードするには、パートナーマネージャーと協力する必要があります。カスタムフォルダー構造は、アセットの作成時に指定する必要があるトークン化されたメタデータのセットです。簡単な例を見てみましょう。

`"A001"`、`"A002"`、`"A003"` などの `reel_name` 値と、`"C001"`、`"C002"` などの `clip_number` 値を持つ 3D カメラリグがあるとします。クリップごとにフォルダーを作成し、左右の目のファイルを入力します。これにより、プロジェクトではファイルが次のように表示されます。

![トークン化されたフォルダーパス - 3D リグの例](/_fern-img/e40b09128d1cbf3c876fd14169a6406642d50d13ce7ab802baff4bbaf50bfd4a.webp)

これを行うには、次の 2 つの設定を行う必要があります。

* 必須メタデータフィールド
* トークン化されたファイルパス

必須メタデータフィールドは、統合のアセット作成時に設定する必要があるキーのシンプルなリストです。

```text
[reel_name, clip_number]
```

次に、これらのキーのいずれかを使用して `/` で区切られたパスを作成し、`{field_name}` を使用してフィールドの値を挿入する場所を示すことができます。

```text
REEL_{reel_name}/{reel_name}_{clip_number}
```

これら両方の設定は、統合の詳細の一部として追加するために、[Frame.io](http://frame.io/) のチームに提供される必要があります。チームによるこれらの設定後、アセットの作成を正常に行うために、これらの値をペイロードのルートに指定する必要があります。

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_LEFT.mp4", 
            "filetype": "video/mp4", 
            "filesize": 21136250,
            "offset": 10,
            "metadata": {
              "reel_name": "A001",
              "clip_number": "C001"
            },
        }
__JSON__
} | python -m json.tool
```

これにより、次のような完全なパスを含むファイルが作成されます。`Cloud Devices`／`2022_04_01`／`VIDEO`／`MY_DEVICE`／`REEL_A001`／`A001_C001`／`A001_C001_LEFT.mp4`

<Error title="Metadata errors">
If your device has not been explicitly set up to allow these fields, you will receive an error if you try to make the same call. Likewise, if you set up required metadata fields, you MUST supply them in the asset create payload or an error will be returned.
</Error>

ペイロードは、すべての有効な JSON 値を受け入れます。文字列以外の値は、次のようにレンダリングされます。

* **整数**：10 進法でレンダリング： `10` -> `"10"`
* **浮動小数点数**：プログラミング言語の設計と実装に関する SIGPLAN '96 会議の議事録の「Printing Floating-Point Numbers Quickly and Accurately（浮動小数点数を高速かつ正確に出力する方法）」で説明されているアルゴリズムに従って、最短表現を使用します。
* **ブール値：**`true` および `false` は、`"true"` と `"false"`としてレンダリングされます
* **null**：空の文字列としてレンダリングされます。`reel_name` を `null` に設定した場合、最初のカスタムフォルダーは `REEL_` としてレンダリングされます。

通常、値を文字列に制限し、他の値の書式を適切に設定することをお勧めします（例えば、整数は常に先頭のゼロなしで出力されるため、変更が必要となる場合があります）。

一般的には、すべてのクリップに対して有効な値を持つフィールドのみを使用します。フィールドが常に有効な値を持つとは限らない場合は、未設定値または null 値を表す方法を検討しておく必要があります。

## バージョンスタッキング

[Frame.io](http://frame.io/) は[バージョンスタック](https://support.frame.io/en/articles/4431-version-stacking-and-comparison)をサポートしています。これは、UI で同じコンテンツの複数のイテレーションをバンドルする方法です。C2C API を使用すると、デバイスはアセットの新しいイテレーションをアップロードして、以前のバージョンと一緒にバージョンスタックに入れることができます。

バージョンスタックを作成するには、`autoversion_id` を指定して、アセットが属するバージョンスタックを識別する必要があります。この値には、UUID、ファイル名などの任意の値を指定できます。アセットフォルダ内で意図せず繰り返されない値のみを使用するように注意してください。例えば、統合で同じファイル名が複数回作成される可能性がある場合、`autoversion_id` **としてファイル名を使用するのはお勧めできません。

次のように autoversion_id を指定します。

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v01.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```

新しいアセットをアップロードするたびに、同じ autoversion_id を使用すると、元のアセットを含むスタックに最新バージョンとしてアセットが追加されます。

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v02_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 10,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```

アセットは、同じフォルダーにアップロードされた場合にのみスタックされるため、バージョンスタッキングを実装する場合は、次の 2 **つの点に注意する必要があります。

* トークン化されたメタデータは、バージョンスタックを作成するために同じ親フォルダーに解決される必要があります。
* 作成日はファイルパスの一部であるため、UTC の午前 0 時以降に作成された新しいバージョンは、元のアップロードの作成日時のオフセットを指定しない限り、正しくスタックされない場合があります。

この 2 つ目のポイントは重要です。最初のアップロードから 48 時間後に、アセットの新しいバージョンが作成されたとします。元のアセットとスタックするには、過去 48 時間のオフセットを指定する必要があります。つまり 172,800 秒です。

```shell
{
curl -X POST https://api.frame.io/v2/assets \
    --header 'Authorization: Bearer [access_token]' \
    --header 'Content-Type: application/json' \
    --header 'x-client-version: 2.0.0' \
    --data-binary @- <<'__JSON__' 
        {
            "name": "A001_C001_v03_with_color.mov", 
            "filetype": "video/webm", 
            "filesize": 21136250,
            "offset": 172800,
            "autoversion_id": "033e22ae-8544-4c9b-a84c-fcc140b0dd16"
        }
__JSON__
} | python -m json.tool
```

最新のアセットが **`2022_04_03` にアップロードされている場合は、`2022_04_01` にアップロードされ、正しいアセットとスタックされます。

## 次のステップ

これは、最適な C2C 統合を作成するための最後のガイドです。自分の背中をたたいて褒めてあげましょう。ご褒美をあげるのもいいですね。あとは、インテグレーターのチェックリストを確認するだけです。このチェックリストには、堅牢な統合を作成するために必要なすべての要約が記載されています。

まだの場合は、当社チームにお問い合わせください。そのうえで、次のガイドに進んでください。ご連絡をお待ちしております。