ローカルおよびリモートアップロードの仕組み

このガイドでは、Frame.io V4 API を使用してファイルをアップロードするための完全なフローを詳しく説明します。

前提条件

ファイルのアップロードを開始する前に、次の設定手順が完了していることを確認してください。

1

Frame.io V4 アカウント

Adobe Admin Console を介して管理されている Frame.io V4 アカウントがあるか、アカウントユーザーの Adobe 認証に切り替え 済みである

2

Adobe Developer Console の設定

Adobe Developer Console にログインし、Frame.io API を新規または既存のプロジェクトに追加した

3

認証資格情報

プロジェクトの 適切な認証資格情報 を生成済みである

4

アクセストークン

これらの認証情報を使用してアクセストークンを正常に生成した

アップロードメソッドの選択

Frame.io API を使用してファイルをアップロードするには、次の 2 つの方法、Create File (local upload) および Create File (remote upload) があります。

ローカルアップロード

デスクトップからファイルをドラッグするのと同様に、メディアがアプリケーションにローカルでアクセスできる場合に使用します

リモートアップロード

別のサービスとの統合など、ネットワーク経由でメディアにアクセスする場合に使用します

このガイドでは、リモートアップロードを完了する簡単なケースから始めます。

リモートアップロード

リモートアップロードを使用してファイルを作成するには、Create File (remote upload) エンドポイントを選択します。リクエスト本文には、ファイル名とそのソース URL が必要です。

要求の例

1{
2 "data": {
3 "name": "my_file.jpg",
4 "source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
5 }
6}

レスポンスの例

要求が成功すると、次のようなレスポンスが返されます。

1{
2 "data": {
3 "id": "93e4079d-0a8a-4bf3-96cd-e6a03c465e5e",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 518,
8 "updated_at": "2025-06-26T20:14:33.796116Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:14:33.159489Z",
13 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e"
14 },
15 "links": {
16 "status": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/files/93e4079d-0a8a-4bf3-96cd-e6a03c465e5e/status"
17 }
18}

ローカルアップロード

ローカルアップロードを使用してファイルを作成するには、Create File (local upload) エンドポイントを選択します。リクエスト本文には、ファイル名とそのファイルサイズをバイト単位で指定する必要があります。

要求の例

1{
2 "data": {
3 "name": "my_file.jpg",
4 "file_size": 50645990
5 }
6}

レスポンスの例

要求が成功すると、コンテンツが含まれないプレースホルダーのファイルリソースが作成されます。ファイルサイズに応じて、応答本文には 1 つ以上の upload_urls が含まれます。この例では、このアップロードを複数のパートで管理する必要があります。

1{
2 "data": {
3 "id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
4 "name": "my_file.jpg",
5 "status": "created",
6 "type": "file",
7 "file_size": 50645990,
8 "updated_at": "2025-06-26T20:08:06.823170Z",
9 "media_type": "image/jpeg",
10 "parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
11 "project_id": "7e46e495-4444-4555-8649-bee4d391a997",
12 "created_at": "2025-06-26T20:08:06.751313Z",
13 "upload_urls": [
14 {
15 "size": 16881997,
16 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
17 },
18 {
19 "size": 16881997,
20 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
21 },
22 {
23 "size": 16881996,
24 "url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
25 }
26 ],
27 "view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
28 }
29}

重要なアップロード要件:

後続のアップロード要求を送信する際には、次の重要な点に注意する必要があります。

  • HTTP 要求メソッドは PUT である必要があります
  • x-amz-acl ヘッダーを含め、「private」に設定する必要があります
  • Content-Type ヘッダーは、元の Create File (local upload) 要求で指定された media_type と一致する必要があります。これは、ファイルを個別の部分としてアップロードする場合でも該当します。上記の例では、media_type の値は image/jpeg です。したがって、Content-Type の値も image/jpeg である必要があります。

マルチパートアップロード

特定のファイルが複数のアップロード URL になる場合、ソースファイルをチャンクに分割し、同じ数の後続する要求を発行するシェルスクリプトを作成すると便利です。

以下の Python スクリプトのサンプルでは、upload_urls パラメーターに複数のアップロード URL を渡しています。

Python の実装例

Multi-part Upload Script
1import requests
2import math
3from typing import List
4from tqdm import tqdm # For progress bar
5
6def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
7 """
8 Upload a file in chunks using presigned URLs.
9 """
10 try:
11 # Auto-detect content type based on file extension
12 if content_type is None:
13 detected_content_type, _ = mimetypes.guess_type(file_path)
14 content_type = detected_content_type # Default fallback
15
16 print(f"Detected content type: {content_type}")
17
18 # Get file size
19 with open(file_path, 'rb') as f:
20 f.seek(0, 2) # Seek to end of file
21 file_size = f.tell()
22
23 # Calculate chunk size if not provided
24 if chunk_size is None:
25 chunk_size = math.ceil(file_size / len(upload_urls))
26
27 print(f"File size: {file_size} bytes")
28 print(f"Chunk size: {chunk_size} bytes")
29 print(f"Number of chunks: {len(upload_urls)}")
30
31 # Upload each chunk
32 with open(file_path, 'rb') as f:
33 with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
34 for i, url in enumerate(upload_urls):
35 start_byte = i * chunk_size
36 end_byte = min(start_byte + chunk_size, file_size)
37
38 # Read chunk from file
39 f.seek(start_byte)
40 chunk = f.read(end_byte - start_byte)
41
42 print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
43
44 # Upload chunk with minimal headers matching the signature
45 response = requests.put(
46 url,
47 data=chunk,
48 headers={
49 'content-type': content_type,
50 'x-amz-acl': 'private'
51 }
52 )
53
54 if response.status_code != 200:
55 print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
56 print(f"Response text: {response.text}")
57 print(f"Response headers: {dict(response.headers)}")
58 return False
59 else:
60 print(f"Chunk {i+1} uploaded successfully!")
61
62 pbar.update(1)
63
64 return True
65
66 except Exception as e:
67 print(f"Error during upload: {str(e)}")
68 return False
69
70# Example usage
71if __name__ == "__main__":
72 # Replace these with your actual values
73 file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
74 upload_urls = [
75 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
76 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
77 "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
78 ]
79 content_type = "image/jpeg"
80
81 print("Starting file upload...")
82 success = upload_file_in_chunks(file_path, upload_urls, content_type)
83
84 if success:
85 print("File upload completed successfully!")
86 else:
87 print("File upload failed!")

アップロードフローの要約

1

アップロードメソッドの選択

リモートアップロード(URL 経由でアクセス可能なファイル)またはローカルアップロード(システム上のファイル)のいずれかを選択します

2

ファイル要求の作成

必要なメタデータを使用して、ファイルリソースを作成するための最初の要求を作成します

3

アップロード URL の処理

ローカルアップロードの場合は、返された upload_urls を処理します(単一または複数のパート)

4

ファイルのコンテンツのアップロード

適切なヘッダーを持つ PUT 要求を使用して、指定された URL にファイルのコンテンツをアップロードします

5

アップロードの検証

ファイルのステータスを確認して、アップロードと処理が正常に完了したことを確認します

次の手順:ファイルのアップロード後、返されたファイル ID を使用して、コメントの追加、共有の作成、または Frame.io V4 API を使用したその他の操作を実行できます。