Как работает локальное и удаленное добавление файлов

В этом руководстве подробно описан весь процесс добавления файлов с использованием API-интерфейса Frame.io V4. В нем рассматриваются необработанные запросы к API-интерфейсу и ответы как для локального, так и для удаленного добавления.

Ищете руководства по конкретным SDK? Инструкции по добавлению с встроенным разделением на фрагменты, выполнением повторных попыток и отслеживанием прогресса — в руководстве по добавлению через SDK для Python.

Предварительные требования

Перед тем как приступить к добавлению файлов, убедитесь, что вы выполнили следующие шаги по настройке.

1

Учетная запись Frame.io V4

У вас есть учетная запись Frame.io V4, управляемая через Adobe Admin Console, ИЛИ вы перевели пользователей своей учетной записи на аутентификацию Adobe.

2

Настройка Adobe Developer Console

Вы вошли в Adobe Developer Console и добавили API-интерфейс Frame.io в новый или существующий проект.

3

Учетные данные для аутентификации

Вы создали соответствующие учетные данные для аутентификации в своем проекте.

4

Токен доступа

Вы успешно использовали эти учетные данные для создания токена доступа.

Выбор метода добавления

Существует два способа добавления файлов через API-интерфейс Frame.io: Создать файл (локальное добавление) и Создать файл (удаленное добавление).

Локальное добавление

Используйте этот метод, если медиафайл доступен вашему приложению локально (аналогично перетаскиванию файла с рабочего стола).

Удаленное добавление

Используйте этот метод, если доступ к медиафайлу осуществляется по сети (например, в рамках интеграции с другим сервисом).

В этом руководстве мы начнем с более простого случая — удаленного добавления.

Удаленное добавление

Чтобы создать файл путем удаленного добавления, выберите конечную точку Создать файл (удаленное добавление). В теле запроса необходимо передать имя файла и URL-адрес его источника.

В настоящее время для удаленного добавления установлено ограничение на размер файла 50 ГБ. Для файлов размером более 50 ГБ используйте локальное добавление.

Пример запроса

{
"data": {
"name": "my_file.jpg",
"source_url": "https://upload.wikimedia.org/wikipedia/commons/e/e1/White_Pixel_1x1.jpg"
}
}

Пример ответа

Успешный запрос вернет ответ, аналогичный приведенному ниже.

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

Локальное добавление

Чтобы создать файл путем локального добавления, выберите конечную точку Создать файл (локальное добавление). В теле запроса необходимо указать имя файла и его размер в байтах.

Пример запроса

{
"data": {
"name": "my_file.jpg",
"file_size": 50645990
}
}

Пример ответа

В случае успешного выполнения запроса создается пустой файл-заполнитель. В зависимости от размера файла тело ответа будет содержать один или несколько URL-адресов добавления upload_urls. В данном примере нам потребуется управлять добавлением частями.

{
"data": {
"id": "fa18ba7b-b3ee-4dd6-9b31-bd07e554241d",
"name": "my_file.jpg",
"status": "created",
"type": "file",
"file_size": 50645990,
"updated_at": "2025-06-26T20:08:06.823170Z",
"media_type": "image/jpeg",
"parent_id": "2e426fe0-f965-4594-8b2b-b4dff1dc00ec",
"project_id": "7e46e495-4444-4555-8649-bee4d391a997",
"created_at": "2025-06-26T20:08:06.751313Z",
"upload_urls": [
{
"size": 16881997,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?..."
},
{
"size": 16881997,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?..."
},
{
"size": 16881996,
"url": "https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
}
],
"view_url": "https://next.frame.io/project/7e46e495-4444-4555-8649-bee4d391a997/view/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d"
}
}

Важные требования к добавлению

Ниже приведены важные детали, которые необходимо учитывать при отправке последующих запросов на добавление.

  • Метод HTTP-запроса должен быть PUT
  • Заголовок x-amz-acl должен быть обязательно включен и иметь значение private.
  • Заголовок Content-Type должен соответствовать типу данных media_type, указанному в исходном запросе Создать файл (локальное добавление). Это правило действует даже в том случае, если файл добавляется отдельными частями. В приведенном выше примере значением media_type является image/jpeg. Соответственно, значение Content-Type также должно быть image/jpeg.

Добавление частями

Если для определенного файла создается более одного URL-адреса добавления, необходимо разделить исходный файл на фрагменты и отправить запрос PUT для каждого из них.

Рекомендация. В руководстве по добавлению с помощью SDK для Python описано добавление частями с помощью компонента FrameioUploader, который обеспечивает разделение на фрагменты, параллельное добавление, выполнение повторных попыток и отслеживание прогресса.

Если необходимо выполнить добавление вручную (например, на языке, для которого нет готового SDK, или ради полного контроля над процессом), приведенный ниже сценарий показывает, как разбить файл на фрагменты и добавить каждый из них с использованием предварительно подписанных URL-адресов.

Пример выполнения на Python

Сценарий добавления частями
import requests
import math
from typing import List
from tqdm import tqdm # For progress bar
def upload_file_in_chunks(file_path: str, upload_urls: list[str], content_type: str | None = None, chunk_size: int | None = None) -> bool:
"""
Upload a file in chunks using presigned URLs.
"""
try:
# Auto-detect content type based on file extension
if content_type is None:
detected_content_type, _ = mimetypes.guess_type(file_path)
content_type = detected_content_type # Default fallback
print(f"Detected content type: {content_type}")
# Get file size
with open(file_path, 'rb') as f:
f.seek(0, 2) # Seek to end of file
file_size = f.tell()
# Calculate chunk size if not provided
if chunk_size is None:
chunk_size = math.ceil(file_size / len(upload_urls))
print(f"File size: {file_size} bytes")
print(f"Chunk size: {chunk_size} bytes")
print(f"Number of chunks: {len(upload_urls)}")
# Upload each chunk
with open(file_path, 'rb') as f:
with tqdm(total=len(upload_urls), desc="Uploading chunks") as pbar:
for i, url in enumerate(upload_urls):
start_byte = i * chunk_size
end_byte = min(start_byte + chunk_size, file_size)
# Read chunk from file
f.seek(start_byte)
chunk = f.read(end_byte - start_byte)
print(f"Uploading chunk {i+1}: {len(chunk)} bytes")
# Upload chunk with minimal headers matching the signature
response = requests.put(
url,
data=chunk,
headers={
'content-type': content_type,
'x-amz-acl': 'private'
}
)
if response.status_code != 200:
print(f"Failed to upload chunk {i+1}. Status code: {response.status_code}")
print(f"Response text: {response.text}")
print(f"Response headers: {dict(response.headers)}")
return False
else:
print(f"Chunk {i+1} uploaded successfully!")
pbar.update(1)
return True
except Exception as e:
print(f"Error during upload: {str(e)}")
return False
# Example usage
if __name__ == "__main__":
# Replace these with your actual values
file_path = "/Users/MyComputer/local_upload/sample.jpg" # Path to your file
upload_urls = [
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_1?...",
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_2?...",
"https://frameio-uploads-development.s3-accelerate.amazonaws.com/parts/fa18ba7b-b3ee-4dd6-9b31-bd07e554241d/part_3?..."
]
content_type = "image/jpeg"
print("Starting file upload...")
success = upload_file_in_chunks(file_path, upload_urls, content_type)
if success:
print("File upload completed successfully!")
else:
print("File upload failed!")

Сводка процесса добавления

1

Выбор метода добавления

Выберите между удаленным добавлением (файл доступен по URL-адресу) или локальным добавлением (файл находится в вашей системе).

2

Запрос на создание файла

Выполните первичный запрос, чтобы создать ресурс для файла с необходимыми метаданными.

3

Обработка URL-адресов добавления

В случае локального добавления обработайте возвращенные URL-адреса (для одной или нескольких частей).

4

Добавление содержимого файла

Используйте запросы PUT с соответствующими заголовками для отправки содержимого файла по предоставленным URL-адресам.

5

Подтверждение добавления

Проверьте статус файла, чтобы подтвердить успешное завершение добавления и обработки.

Следующие шаги. Как только ваш файл будет добавлен, вы сможете использовать полученный идентификатор файла, чтобы оставлять комментарии, создавать общие ресурсы или выполнять другие операции, используя API-интерфейс Frame.io V4.