Руководство по началу работы

Adobe Developer Console

Первым шагом при использовании любого API-интерфейса Adobe является создание проекта в Adobe Developer Console. Проекты в Developer Console соответствуют приложению, которое вы создаете для использования API-интерфейса Frame.io Developer. Обратите внимание, что эта сущность отличается от проекта внутри Frame.io.

После создания проекта в Developer Console добавьте в него API-интерфейс Frame.io.

Что нового в API-интерфейсе Frame.io V4 Developer?

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

В API-интерфейсе V4 некоторые ресурсы были переименованы, чтобы соответствовать интерфейсу Frame.io версии 4 (например, рабочие среды, которые в прошлых версиях Frame.io назывались командами). Другие сущности, например «ресурсы» в старой версии, были переименованы в конкретные объекты хранения (файлы, папки и стеки версий), чтобы уменьшить путаницу среди разработчиков. Третьи, например пользовательские поля и общие ресурсы, являются совершенно новыми. Помимо прочих существенных изменений, мы значительно сократили объем данных, возвращаемых по умолчанию при запросах к ресурсам, переименовали некоторые названия свойств в наших ответах для большей точности и согласованности во всем пространстве API-интерфейса, а также перешли на новый механизм разбивки на страницы на основе курсора. В связи с этим важно понимать, что за исключением API-интерфейса «С камеры в облако» (C2C), клиенты, интегрированные со старой версией API-интерфейса, несовместимы с API-интерфейсом V4.

Кроме того, некоторые функции все еще находятся в процессе разработки. Они будут добавляться и совершенствоваться с учетом реальных сценариев использования и отзывов наших клиентов. В качестве примера можно привести возможность создания пользовательских действий и стеков версий. Если вам кажется, что какая-то функция, доступная в старой версии API-интерфейса, сейчас отсутствует, вполне вероятно, что для нее появилась альтернатива или же она станет доступна в ближайшее время. Тем не менее мы будем рады получить от вас обратную связь по этому поводу.

Прежде чем погрузиться в API-интерфейс V4, полезно сначала разобраться в основных понятиях, заложенных в самом приложении Frame.io версии 4. Отличной отправной точкой для этого является база знаний Frame.io V4. Такие понятия, как учетные записи, пользователи, рабочие среды, проекты, коллекции, общие ресурсы и пользовательские поля (метаданные) моделируются как отдельные ресурсы в API-интерфейсе V4. Понимание их взаимосвязей и возможностей в самом приложении поможет вам быстрее разобраться, как они работают в API-интерфейсе V4.

Обзор API-интерфейса

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

Соглашения по URL-адресам и путям

Пути URL-адресов, опубликованные в спецификации OpenAPI, обычно отражают отношения принадлежности и содержания ресурсов. Поэтому некоторые параметры запроса (например, идентификаторы учетных записей, идентификаторы папок и т. д.) встраиваются непосредственно в путь к ресурсу. Хотя эти пути должны быть предсказуемыми и простыми для понимания, структура некоторых URL-адресов, возвращаемых в ответ на запросы к API-интерфейсу (например, предварительно подписанные ссылки для добавления или ссылки для отображения), может со временем меняться. Такие ссылки не должны формироваться напрямую клиентскими приложениями.

Параметры запроса

Параметры запроса, которые управляют механизмом разбивки на страницы и возможностью включения связанных ресурсов в объекты ответа, определены как стандартный набор параметров запроса: include, page_size, include_total_count. Некоторые запросы могут поддерживать дополнительные параметры, специфичные для конкретного ресурса или операции.

1
GET https://api.frame.io/v4/accounts/{account_id}/folders/{folder_id}/children?&include=project&page_size=5&include_total_count=true

Полезная нагрузка запроса и ответа

Полезная нагрузка в запросах и ответах формируется в виде объектов JSON. В связи с этим в HTTP-запросах POST, PUT или PATCH заголовок content-type должен обязательно указывать медиа-тип application/json. При создании или обновлении ресурсов свойство data в запросе должно содержать объект ресурса. Атрибуты создаваемого или обновляемого ресурса содержатся в этом объекте. Аналогичным образом ответы, содержащие ресурсы, передают их в свойстве data ответа.

Разбивка на страницы

Ответы, которые потенциально могут возвращать большое количество объектов ресурсов (например, списки папок или комментариев), разбиваются на страницы, чтобы снизить задержку запроса по мере роста набора результатов. Это означает, что ответ на запрос может содержать только одну «страницу» результатов. Как упоминалось выше, при выполнении запроса клиент может самостоятельно указать конкретный размер страницы (максимум до 100 элементов) с помощью параметра запроса page_size. Если этот параметр не задан, размер страницы по умолчанию составит 50 элементов. API-интерфейс V4 использует форму разбивки на страницы, известную как пагинация на основе курсора и включает в объект ответа относительную ссылку в свойстве links (см. пример ниже), которая содержит непрозрачный курсор в параметре запроса after (клиенты не должны пытаться создать эту строку самостоятельно). Этот параметр позволяет получать следующую страницу результатов (см. пример ответа ниже) при выполнении последующих запросов. В настоящее время API-интерфейс V4 поддерживает разбивку на страницы только в одном направлении.

1
{
2
    "data": [
3
        {
4
            "created_at": "2024-10-02T00:22:44.887775Z",
5
            "creator_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
6
            "file_size": 102432,
7
            "id": "df171f3e-c95f-4454-9071-825cd924b572",
8
            "media_type": "application/pdf",
9
            "name": "sample.pdf",
10
            "parent_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
11
            "project": {
12
                "created_at": "2024-08-21T17:45:41.881596Z",
13
                "description": "For demonstration purposes",
14
                "id": "976dd413-a92b-4af6-b465-98aded0174a8",
15
                "name": "Demo Project",
16
                "owner_id": "8ea72912-d40d-4b88-8d31-3762e055a2aa",
17
                "root_folder_id": "e183c7ba-07d9-425a-9467-ebdf0223d9ce",
18
                "storage": 20881946,
19
                "updated_at": "2024-10-02T00:22:47.168489Z",
20
                "workspace_id": "378fcbf7-6f88-4224-8139-6a743ed940b2"
21
            },
22
            "project_id": "976dd413-a92b-4af6-b465-98aded0174a8",
23
            "status": "created",
24
            "type": "file",
25
            "updated_at": "2024-10-02T00:22:44.927993Z"
26
        }
27
    ],
28
    "links": {
29
        "next": "/v4/accounts/6f70f1bd-7e89-4a7e-b4d3-7e576585a181/folders/e183c7ba-07d9-425a-9467-ebdf0223d9ce/children?after=g3QAAAACZAAGb2Zmc2V0YQVkAAR0eXBlZAANb2Zmc2V0X2N1cnNvcg%3D%3D"
30
    },
31
    "total_count": 21
32
}

Ошибки

В случае возникновения ошибки свойство errors в объекте ответа будет содержать массив из одного или нескольких объектов ошибок с подробными сведениями о произошедшем. На данный момент API-интерфейс V4 не поддерживает пакетные операции, поэтому ситуации, когда клиентскому приложению приходится обрабатывать частичный успех и ошибки, исключены.

1
{
2
    "errors": [
3
        {
4
            "detail": "Unexpected field: foo",
5
            "source": {
6
                "pointer": "/data/foo"
7
            },
8
            "title": "Invalid value"
9
        }
10
    ]
11
}

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

Аутентификация и авторизация

API-интерфейс V4 использует протокол OAuth 2.0 и службу Adobe Identity Management Server (IMS) для аутентификации пользователя (AuthN) и создания токенов доступа от имени этого пользователя. Токен доступа должен передаваться в каждом запросе к API-интерфейсу через HTTP-заголовок Authorization (аутентификация с помощью токена Bearer).

Версии и обратная совместимость

API-интерфейс Frame.io V4 не обладает обратной совместимостью с предыдущими версиями API-интерфейсов Frame.io. Как правило, его нельзя использовать для доступа к ресурсам устаревших учетных записей или для их обновления, поскольку концепции и модель данных в V4 претерпели значительные изменения. В связи с этим все URI, связанные с API-интерфейсом V4, содержат префикс пути /v4. Тем не менее, API-интерфейс V4 продолжает быстро развиваться, поэтому появление новых функций может иногда требовать внесения критических изменений. Чаще Frame.io будет выпускать новые дополнения к API-интерфейсу, которые мы считаем экспериментальными в течение определенного срока, что позволяет нам получать отзывы клиентов и метрики использования, а также реагировать на них. Мы понимаем, что обратная совместимость критически важна для клиентов, управляющих готовыми интеграциями с высокими требованиями к бесперебойной работе. Поэтому мы разрабатываем API-интерфейс V4, который будет поддерживать дополнительные возможности управления версиями через пользовательский заголовок HTTP. Это позволит клиентам использовать экспериментальные конечные точки, избегая критических изменений, и обеспечит обратную совместимость внутри пространства имен V4. Подробности будут опубликованы позже, но сейчас можно с уверенностью предположить, что первоначальный выпуск API-интерфейса V4 является стабильным, и пройдет немало времени, прежде чем мы задумаемся о внесении критических изменений.

Ограничение частоты запросов

Частота всех вызовов API-интерфейса V4 ограничивается, при этом для каждого ресурса и операции API-интерфейса настраивается собственный лимит. Ограничения варьируются от минимального значения 10 запросов в минуту до максимального лимита 100 запросов в секунду. В настоящее время каждый лимит применяется на уровне пользователя, но сами политики и ограничения могут изменяться.

API-интерфейс V4 использует алгоритм дырявого ведра для прогрессивного ограничения частоты запросов, при котором лимиты восстанавливаются постепенно в течение отведенного временного окна. Другими словами, не применяется полный сброс, после которого происходит восстановление лимитов для конкретного ресурса, что характерно для стратегий «фиксированного» и «скользящего окна». Вместо этого оставшиеся лимиты постоянно обновляются со скоростью, пропорциональной общему лимиту ресурса и его временному окну. Запросы, превышающие установленное ограничение для определенной конечной точки, отклоняются с ошибкой HTTP 429.

Рекомендуемая нами стратегия реагирования на ошибки 429 обычно называется «экспоненциальной задержкой».

В кратком виде ее можно изложить следующим образом.

• При получении ошибки 429 сделайте паузу (минимум на одну секунду), прежде чем повторить запрос.
• Если снова возвращается ошибка 429, увеличивайте предыдущий период ожидания экспоненциально (или по крайней мере удваивайте его) до тех пор, пока не будет восстановлена нормальная работа.

Чтобы определить лимиты, применимые к конкретному запросу, клиенты могут проверить следующие HTTP-заголовки, возвращаемые в ответе.

Сведения об API-интерфейсе

Основным источником документации по API-интерфейсу V4 является наш справочник по API-интерфейсу, однако перед отправкой первых запросов будет полезно разобраться в иерархии ресурсов, смоделированной в API-интерфейсе V4.

Иерархия ресурсов

Учетная запись обычно связана с организацией и представляет собой фундаментальный ресурс, который определяет план подписки, владение контентом, роли и права пользователей, а также организацию рабочей среды. В связи с этим URL-путь почти ко всем конечным точкам в API-интерфейсе V4 содержит префикс, идентифицирующий учетную запись, в которой находится данный ресурс. Рабочие среды (называвшиеся командами в предыдущей версии Frame.io) и проекты используются для систематизации как контента, так и пользователей, включая то, кто имеет доступ к тем или иным материалам.

Базовая иерархия ресурсов контента в Frame.io выглядит следующим образом.

Каждый ресурс, добавленный в Frame.io, в конечном итоге представляется в виде файла. При этом папки и стеки версий являются ресурсами хранения, которые выступают в роли контейнеров и обеспечивают основу для иерархической модели хранения с поддержкой версий ресурсов. Большинство пользователей уже знакомы с базовым понятием папки в Frame.io: она просто служит неупорядоченным контейнером для других ресурсов хранения (моделируемых как ее дочерние элементы) и представляет собой узел в дереве папок. Каждый проект имеет уникальную корневую папку (идентифицируемую ключом root_folder_id), которая является корнем дерева папок, где и располагаются все ресурсы этого проекта.

Стек версий — это упорядоченный контейнер для файлов. Порядок в нем является строго линейным и определяет номер версии для каждого из дочерних элементов, однако клиенты могут переставлять файлы внутри стека версий по своему усмотрению. Файл всегда является дочерним элементом (который содержится внутри) ровно одной папки или стека версий. Аналогичным образом папка или стек версий всегда являются дочерними элементами ровно одной папки (за исключением корневой папки проекта).

Подробнее о выполнении базовых операций CRUD с файлами и папками, хранящимися в Frame.io, — в справочнике по API-интерфейсу. В настоящее время API-интерфейс V4 поддерживает стеки версий только при выводе содержимого папки, однако конечные точки для создания и обновления стекoв версий появятся в ближайшем времени.

SDK

SDK доступны для TypeScript и Python. Вы можете установить их с помощью приведенных ниже команд. Полные руководства по SDK для Python и TypeScript содержатся в разделе документации «Справочник по SDK».

TypeScript

$
npm i -s frameio

Посмотреть в npm

Python

$
pip install frameio

Посмотреть в PyPi