Leitfaden „Erste Schritte“

Adobe Developer Console

Der erste Schritt bei der Verwendung einer Adobe-API besteht darin, in der Adobe Developer Console ein Projekt zu erstellen.Projekte in der Developer Console entsprechen einer Anwendung, die Sie entwickeln, um die Developer-API in Frame.io zu nutzen.Dies unterscheidet sich von einem Projekt innerhalb von Frame.io.

Nachdem Sie in der Developer Console ein Projekt erstellt haben, fügen Sie diesem die Frame.io-API hinzu.

Neue Funktionen in der Frame.io V4-Developer-API

Genau wie die Frame.io-Anwendung für die 4. Version vollständig transformiert wurde, wurde auch die V4-API von Grund auf neu entwickelt.Obwohl einige wichtige Konzepte ähnlich bleiben wie in älteren Versionen, wurden viele ersetzt oder neu entwickelt, um leistungsfähigere Zusammenarbeits-Workflows und Integrationen zu unterstützen.Die Einführung einer völlig neuen API bot auch die Gelegenheit, unsere Flüsse drastisch zu vereinfachen und wichtige Workflows der Kundschaft zu priorisieren.

In der V4-API wurden einige Ressourcen wie Arbeitsbereiche (in der älteren Version von Frame.io als Teams bezeichnet) umbenannt, um sie an Frame.io Version 4 anzugleichen. Andere, etwa Assets in der Vorgängerversion, wurden umbenannt, um auf spezifische Speicherentitäten (Dateien, Ordner und Versionsstapel) zu verweisen und die Verwirrung bei den Entwickelnden zu reduzieren.Wieder andere, zum Beispiel selbstdefinierte Felder und Freigaben, sind völlig neu.Unter anderen wesentlichen Änderungen haben wir die standardmäßig zurückgegebene Datenmenge für Ressourcenanfragen drastisch reduziert, einige Eigenschaftsnamen in unseren Antworten umbenannt, um über die gesamte API-Oberfläche genauer und konsistenter zu sein, und zu einem neuen, cursorbasierten Paginierungsmechanismus gewechselt.Daher ist unbedingt zu beachten, dass mit Ausnahme von Kamera zu Cloud (C2C) API-Clients, die mit der älteren API integrieren, nicht mit der V4-API kompatibel sind.

Außerdem befinden sich einige Funktionen noch in Entwicklung. Wir gehen davon aus, dass diese rasch folgen werden und sich in Reaktion auf reale Anwendungsfälle und Feedback von der Kundschaft schnell weiterentwickeln.Beispiele enthalten die Fähigkeit, selbstdefinierte Aktionen und Versionsstapel zu erstellen.Wenn eine Funktion, die in unserer älteren API verfügbar war, zu fehlen scheint, gibt es sehr wahrscheinlich eine Alternative, oder eine solche wird bald verfügbar sein. Diesbezüglich würden wir aber gerne von Ihnen hören.

Bevor Sie in die V4-API eintauchen, sollten Sie sich zunächst mit den Kernkonzepten vertraut machen, die in der Frame.io-Anwendung Version 4 zum Ausdruck gebracht werden.Ein guter Ausgangspunkt ist die Frame.io V4-Wissensdatenbank.Konzepte wie Konten, Benutzende, Arbeitsbereiche, Projekte, Sammlungen, Freigaben und selbstdefinierte Felder (Metadaten) sind in der V4-API als unterschiedliche Ressourcen modelliert. Wenn Sie deren Beziehungen und Fähigkeiten in der Anwendung kennen, können Sie verstehen, wie sie in der V4-API funktionieren.

Überblick über die API

Die Frame.io V4-API ist darauf ausgelegt, RESTful-Architekturprinzipien zu folgen. Standardmäßige HTTP-Methoden und Antwortcodes werden in Verbindung mit einzigartigen, ressourcenspezifischen URLs verwendet.In Frame.io wird eine OpenAPI 3.0-Spezifikation für unsere V4-API veröffentlicht, die detaillierte Informationen über Endpunkte, Anfrageparameter und Antworten enthält.Die OpenAPI-Spezifikation kann von verschiedenen Codegenerierungstools von Drittanbietern genutzt werden, um die Entwicklung von Client-Anwendungen zu beschleunigen.

Konventionen für URLs und Pfade

URL-Pfade, die in der OpenAPI-Spezifikation veröffentlicht werden, spiegeln im Allgemeinen Ressourcenbesitz und Containment-Beziehungen wider.Daher sind einige Anfrageparameter (z. B. Konto-IDs, Ordner-IDs usw.)in den Ressourcenpfad eingebettet.Obwohl diese Pfade vorhersagbar und leicht verständlich sein sollen, kann sich die Struktur einiger URLs ändern, die von API-Anfragen zurückgegeben werden (z. B. vorsignierte Upload-URLs oder Anzeige-Links), und sollten daher niemals direkt von einer Client-Anwendung erstellt werden.

Anfrageparameter in Abfragen

Anfrageparameter, mit denen das Paginierungsverhalten und die optionale Einbindung verwandter Ressourcen in Antwortobjekte gesteuert wird, sind als Standardsatz von Abfrageparametern definiert: include, page_size, include_total_count.Einige Anfragen können zusätzliche Abfrageparameter unterstützen, die für diese Ressource oder Operation spezifisch sind.

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

Anfrage- und Antwort-Payloads

Anfrage- und Antwort-Payloads bestehen beide aus JSON-Objekten, und daher muss im Content-Type-Header einer HTTP POST-, PUT- oder PATCH-Anfrage der Medientyp application/json angegeben werden.Beim Erstellen oder Aktualisieren von Ressourcen muss die Eigenschaft data der Anfrage das Ressourcenobjekt enthalten.Attribute der zu erstellenden oder zu aktualisierenden Ressource sind in diesem Objekt enthalten.Ebenso stellen erfolgreiche Antworten, die Ressourcen enthalten, diese innerhalb der Eigenschaft data der Antwort bereit.

Paginierung

Antworten, bei denen möglicherweise große Mengen von Ressourcenobjekten zurückgegeben werden (z. B. Auflistungen von Ordnern oder Kommentaren), werden paginiert, um die Anfragelatenz zu reduzieren, wenn der Ergebnissatz größer wird. Das bedeutet, dass die Antwort auf eine Anfrage möglicherweise nur eine einzelne „Seite” von Ergebnissen enthält.Wie bereits erwähnt, kann ein Client bei der Anfrage über den Abfrageparameter page_size eine bestimmte Seitengröße von bis zu 100 Elementen wählen.Falls nicht angegeben, umfasst die Standardseitengröße 50 Elemente.In der V4-API wird eine Form der Paginierung verwendet, die als cursorbasierte Paginierung bekannt ist. Diese enthält in der Eigenschaft links des Antwortobjekts einen relativen Link (siehe Beispiel unten). Dieser wiederum enthält eine intransparente Cursor-Zeichenfolge (Clients sollten nicht versuchen, diese Zeichenfolge selbst zu erstellen) im Abfrageparameter after. Damit kann vom Client die nächste Seite der Ergebnisse abgerufen werden (siehe Beispielantwort unten), indem nachfolgende Anfragen gestellt werden.Derzeit wird nur unidirektionale Paginierung von der V4-API unterstützt .

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
}

Fehler

Falls ein Fehler auftritt, enthält die Eigenschaft errors im Antwortobjekt ein Array aus einem oder mehreren Fehlerobjekten, die Details über den/die aufgetretenen Fehler bereitstellen.Derzeit werden Batch-Bearbeitungen nicht von der V4-API unterstützt, sodass es keine Fälle gibt, in denen teilweiser Erfolg und Fehler vom Client verarbeitet werden müssen.

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

In der folgenden Tabelle sind häufige Statuscodes aufgelistet, die von der V4-API verwendet werden.

Authentifizierung und Autorisierung

Die V4-API basiert auf OAuth 2.0 und Adobe Identity Management Server (IMS), damit Benutzende authentifiziert (AuthN) und im Namen dieser Benutzenden Zugriffstoken generiert werden können.Bei jeder API-Anfrage über den HTTP-Authorization-Header muss ein Zugriffstoken bereitgestellt werden (d. h. Bearer-Token-Authentifizierung).

Versionen und Abwärtskompatibilität

Die Frame.io V4-API ist nicht mit früheren Versionen von Frame.io-APIs abwärtskompatibel und kann im Allgemeinen nicht verwendet werden, um in älteren Konten auf Ressourcen zuzugreifen oder diese zu aktualisieren, da es in den V4-Konzepten und im Datenmodell erhebliche Änderungen gegeben hat.Daher enthalten alle URIs der V4-API das Pfadpräfix /v4.Die V4-API wird jedoch immer noch weiterentwickelt, und es ist möglich, dass neue Funktionen gelegentlich Breaking Changes rechtfertigen.Häufiger wird Frame.io neue Erweiterungen der API veröffentlichen, die wir für einen bestimmten Zeitraum als experimentell betrachten, damit wir Rückmeldungen und Nutzungsmetriken von der Kundschaft erhalten und darauf reagieren können.Da wir wissen, dass Abwärtskompatibilität ein wichtiges Anliegen für die Kundschaft ist, die Integrationen in Produktionsqualität mit hohen Anforderungen an die Verfügbarkeit verwalten, entwickeln wir die V4-API so, dass über einen selbstdefinierten HTTP-Header eine zusätzliche Versionierungsebene unterstützt wird. So können Clients experimentelle Endpunkte nutzen, Breaking Changes vermeiden und Abwärtskompatibilitätsgarantien innerhalb des V4-Namespace erhalten.Weitere Details folgen, doch vorerst können Sie davon ausgehen, dass die erste Veröffentlichung der V4-API als stabil gilt und dass es einige Zeit dauern wird, bevor wir die Einführung von Breaking Changes in Betracht ziehen.

Ratenbegrenzung

Alle Aufrufe der V4-API sind ratenbegrenzt, und alle API-Ressourcen und -Operationen sind mit einem eigenen Grenzwert konfiguriert. Die Grenzwerte reichen von nur 10 Anfragen pro Minute bis hin zu 100 Anfragen pro Sekunde.Derzeit werden die einzelnen Grenzwerte pro Benutzer bzw. Benutzerin durchgesetzt, aber die Regeln und die Grenzwerte selbst können sich ändern.

In der V4-API wird ein Leaky Bucket-Algorithmus für progressive Ratenbegrenzung eingesetzt, bei dem die Grenzwerte während ihres zugewiesenen Zeitfensters schrittweise aktualisiert werden.Mit anderen Worten gibt es keinen festen Grenzwert, ab dem die Ratenbegrenzungen für eine bestimmte Ressource aktualisiert werden (d. h. keine „festen“ oder „gleitenden“ Durchsetzungsstrategien).Vielmehr werden die verbleibenden Grenzwerte kontinuierlich aktualisiert, wobei das Tempo von dem Grenzwert der jeweiligen Ressource und dem Zeitfenster abhängt.Anfragen, bei denen die Ratenbegrenzung für einen bestimmten Endpunkt überschritten werden, schlagen mit dem HTTP-Fehler 429 fehl.

Unsere empfohlene Strategie für die Reaktion auf 429-Fehler wird normalerweise als „exponentieller Rückzug“ bezeichnet.

Kurz gesagt:

• Wenn Sie einen 429 erhalten, pausieren Sie kurz (mindestens eine Sekunde), bevor Sie die Anfrage wiederholen.
• Erhalten Sie einen weiteren 429, erhöhen Sie die vorherige Wartezeit exponentiell oder verdoppeln Sie sie zumindest, bis die normale Funktion wieder aufgenommen wird.

Zur Ermittlung der Ratenbegrenzungen, die für eine bestimmte Anfrage gelten, können die folgenden HTTP-Header in der Antwort von den Clients überprüft werden:

API-Details

Die maßgebliche Dokumentation zur V4-API ist unser API-Referenzleitfaden. Es ist jedoch hilfreich, die von der V4-API modellierte Ressourcenhierarchie zu verstehen, bevor Sie Ihre ersten Anfragen stellen.

Ressourcenhierarchie

Ein Konto ist in der Regel mit einer Organisation verknüpft und stellt die grundlegende Ressource dar, mit der ein Abonnementplan, Verantwortung für Inhalte, Benutzendenrollen/Berechtigungen und Arbeitsbereichsorganisation bestimmt werden.Daher enthält der URL-Pfad zu fast allen Endpunkten in der V4-API ein Präfix, mit dem das Konto identifiziert wird, in dem sich die Ressource befindet.In Arbeitsbereichen (in der Vorgängerversion von Frame.io Teams genannt) und Projekten werden sowohl Inhalte als auch Benutzende organisiert, einschließlich wer auf welche Inhalte zugreifen darf.

Die grundlegende Hierarchie der Inhaltsressourcen innerhalb von Frame.io ist wie folgt:

Jedes Asset, das in Frame.io hochgeladen wird, wird letztendlich als Datei dargestellt, während Ordner und Versionsstapel Speicherressourcen sind, die als Container fungieren und die Grundlage für ein hierarchisches Speichermodell bilden, in dem versionierte Assets unterstützt werden.Die meisten Benutzenden sind bereits mit dem grundlegenden Konzept eines Ordners in Frame.io vertraut: Er dient einfach als ungeordneter Container für andere Speicherressourcen (modelliert als seine Unterelemente) und stellt einen Knoten innerhalb der Ordnerstruktur dar.Jedes Projekt hat einen eindeutigen Stammordner (identifiziert durch den Schlüssel root_folder_id), der als Stamm der Ordnerstruktur dient, in der alle Assets eines Projekts gespeichert sind.

Ein Versionsstapel ist ein geordneter Container von Dateien.Seine Reihenfolge ist streng linear, für jedes seiner Unterelemente wird eine Versionsnummer bestimmt, aber die Kundschaft kann die Dateien innerhalb des Versionsstapels nach Belieben neu ordnen.Eine Datei wird jederzeit ein Unterelement von genau einem Ordner oder Versionsstapel (darin enthalten) sein.Ebenso wird ein Ordner oder Versionsstapel immer ein Unterelement von genau einem Ordner sein (ausgenommen der Stammordner des Projekts).

Weitere Details zum Durchführen grundlegender CRUD-Operationen an Dateien und Ordnern, die in Frame.io gespeichert sind, finden Sie im API-Referenzleitfaden.Derzeit werden Versionsstapel nur beim Auflisten der Inhalte eines Ordners von der V4-API unterstützt, aber demnächst sind Endpunkte zum Erstellen und Aktualisieren von Versionsstapeln verfügbar.

SDKs

Es gibt SDKs für TypeScript und Python.Sie können sie mit den folgenden Befehlen installieren.Der Abschnitt „SDK-Referenz“ der Dokumentation enthält vollständige Referenzen für die Python- und TypeScript-SDKs.

TypeScript

$
npm i -s frameio

Auf npm anzeigen

Python

$
pip install frameio

Auf PyPi anzeigen.