How-to-Anleitungen

Leitfaden: Assets organisieren

Einführung

In diesem Leitfaden erfahren wir, wie und in welchem Umfang wir steuern können, wo Assets aus Ihrer Integration hochgeladen werden.

Was benötige ich?

Falls Sie den Leitfaden C2C implementieren: Einrichtung noch nicht gelesen haben, werfen Sie bitte einen kurzen Blick darauf, bevor Sie fortfahren!Sie benötigen auch den access_token, den Sie mit dem Leitfaden zur Authentifizierung und Autorisierung für die C2C-Hardware oder C2C-Anwendung erhalten haben.

Struktur des Asset-Ordners

Standardmäßig werden Assets mit der folgenden Ordnerstruktur erstellt:

Cloud Devices > {YYYY}_{MM}_{DD} > {ASSET_TYPE} > {YOUR_DEVICE} > {ASSET_NAME} Wobei {ASSET_TYPE} entweder VIDEO, AUDIO oder DATA ist (je nach Gerätemodell pro Kanal konfiguriert), {YOUR_DEVICE} der Name des mit dem Projekt des Benutzenden verbundenen Projektgeräts ist und {ASSET_NAME} der Name des von Ihnen hochgeladenen Assets ist, das tatsächlich in Frame.io abgespielt werden kann.

Erweiterungsrouting

Sie können Ihr Gerät so einrichten, dass verschiedene Assets je nach Dateiendung in {ASSET_NAME} in selbstdefinierte {ASSET_TYPE}-Ordner weitergeleitet werden.Nehmen wir zum Beispiel an, Ihre Integration erzeugt eine Reihe verschiedener Dateitypen, die jeweils einer bestimmten Herkunft zuzuordnen sind.Sie können uns anweisen, diese Assets wie folgt zuzuordnen:

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

Wenn Sie nun das folgende Asset erstellen:

${
>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
Spezifikation des API-Endpunkts

Die Dokumente für /v2/assets können Sie hier finden

… wird es an einen Speicherort wie den folgenden weitergeleitet: Cloud Devices > 2022_04_01 > STILLS > MY_DEVICE > IMAGE_0001.jpeg.Hieße die Datei stattdessen A001_C001.mov, würde sie unter folgendem Pfad gespeichert: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > A001_C001.mov.

Tokenisierte Upload-Pfade

Einige Integrationen möchten möglicherweise mehr Kontrolle über die Ordnerstruktur haben, die ihr Gerät erstellt.Wir bei Frame.io müssen unsererseits sicherstellen, dass beim Hochladen von Dateien von einem C2C-Gerät auf Frame.io ein gewisses Maß an Konsistenz gewährleistet ist, und der Frame.io-Kundschaft insbesondere garantieren, mit welchem Teil ihres Projekts ein C2C-Gerät interagieren kann.Zu diesem Zweck ermöglichen wir Integratoren, die Speicherorte für ihre Assets innerhalb des Ordners {YOUR_DEVICE} individuell anzupassen, lassen jedoch nicht zu, dass Assets außerhalb dieses Ordners hochgeladen werden.

Zum Hochladen in eine selbstdefinierte Ordnerstruktur müssen Sie mit Ihrem Partner Manager zusammenarbeiten.Selbstdefinierte Ordnerstrukturen sind eine Gruppe von tokenisierten Metadaten, die bei der Asset-Erstellung angegeben werden müssen.Nehmen wir ein einfaches Beispiel:

Nehmen wir an, wir haben ein 3D-Kamera-Rig mit reel_name-Werten wie &quot;A001&quot;, &quot;A002&quot;, &quot;A003&quot; usw. und clip_number-Werten wie &quot;C001&quot;, &quot;C002&quot; usw. Wir möchten für jeden Clip Ordner erstellen und diese mit den Dateien für das linke und rechte Auge füllen, sodass die Dateien in einem Projekt wie folgt aussehen würden: Tokenisierter Ordnerpfad – 3D Rig-Beispiel

Dazu müssen wir zwei Einstellungen konfigurieren:

  • Erforderliche Metadatenfelder
  • Tokenisierter Dateipfad

Erforderliche Metadatenfelder sind eine einfache Liste von Schlüsseln, die bei der Asset-Erstellung für Ihre Integration festgelegt werden müssen:

[reel_name, clip_number]

Sie können dann jeden dieser Schlüssel verwenden, um einen durch / getrennten Pfad zu erstellen, wobei {field_name} angibt, an welcher Stelle der Wert eines Feldes eingefügt werden soll:

REEL_{reel_name}/{reel_name}_{clip_number}

Beide Einstellungen müssen unserem Team bei Frame.io mitgeteilt werden, um sie als Teil der Integrationsdetails hinzuzufügen.Sobald wir das eingerichtet haben, müssen diese Werte beim Erstellen eines Assets an der obersten Ebene der Payloads angegeben werden, damit die Erstellung des Assets erfolgreich verläuft:

${
>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

Dadurch wird eine Datei mit folgendem vollständigen Pfad erstellt: Cloud Devices > 2022_04_01 > VIDEO > MY_DEVICE > REEL_A001 > A001_C001 > A001_C001_LEFT.mp4

Metadatenfehler

Wenn Ihr Gerät nicht ausdrücklich für die Verwendung dieser Felder konfiguriert wurde, erhalten Sie eine Fehlermeldung, wenn Sie versuchen, denselben Anruf zu tätigen.Ebenso MÜSSEN Sie, wenn Sie obligatorische Metadatenfelder festlegen, diese in der Payload zum Anlegen des Assets angeben, da andernfalls ein Fehler zurückgegeben wird.

Die Payload akzeptiert jeden gültigen JSON-Wert.Werte, die keine Zeichenfolgen sind, werden wie folgt wiedergegeben:

  • integers: Ausgegeben in base-10: 10 -> &quot;10&quot;
  • floats: Verwendet die kürzeste Darstellung gemäß dem Algorithmus, der in „Printing Floating-Point Numbers Quickly and Accurately“ in den Proceedings der SIGPLAN-Konferenz ’96 über Entwurf und Implementierung von Programmiersprachen beschrieben ist.
  • booleans: true und false werden als &quot;true&quot; und &quot;false&quot; ausgegeben
  • null: Wird als leere Zeichenfolge ausgegeben.Wenn reel_name auf null festgelegt ist, wird der erste selbstdefinierte Ordner als REEL_ ausgegeben

Im Allgemeinen empfehlen wir Ihnen, Ihre Werte auf Zeichenfolgen zu begrenzen und andere Werte entsprechend zu formatieren (z. B. Ganzzahlen werden immer ohne führende Nullen gedruckt, etwas, das Sie vielleicht anpassen möchten).

Generell sollten nur Felder verwendet werden, die für jeden Clip einen gültigen Wert haben; wenn ein Feld nicht immer einen gültigen Wert hat, sollten Sie einen Plan haben, wie nicht festgelegte oder Nullwerte dargestellt werden sollen.

Versionsstapelung

Frame.io unterstützt Versionsstapel – eine Möglichkeit, mehrere Iterationen mit demselben Inhalt in der UI zu bündeln.Über die C2C-API können Geräte neue Versionen eines Assets hochladen, die zusammen mit den vorherigen Versionen in einen Versionsstapel aufgenommen werden.Um einen Versionsstapel zu erstellen, müssen Sie eine autoversion_id angeben, um festzulegen, zu welchem Versionsstapel die Assets gehören.Dieser Wert kann beliebig sein: eine UUID, ein Dateiname usw. Achten Sie darauf, nur Werte zu verwenden, die in einem Asset-Ordner niemals unbeabsichtigt doppelt vorkommen.Wenn es beispielsweise möglich ist, dass Ihre Integration denselben Dateinamen mehr als einmal erstellt, dann ist der Dateiname kein geeigneter Kandidat für die autoversion_id.

Wir stellen eine autoversion_id folgendermaßen bereit:

${
>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

Wenn Sie jetzt ein neues Asset hochladen und dieselbe autoversion_id verwenden, wird das Asset als neueste Version in einem Stapel mit dem ursprünglichen Asset hinzugefügt:

${
>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

Assets werden nur dann gestapelt, wenn sie in denselben Ordner hochgeladen werden. Daher müssen Sie einige Dinge beachten, wenn Sie das Stapeln von Versionen implementieren möchten:

  • Tokenisierte Metadaten müssen auf denselben übergeordneten Ordner verweisen, damit der Versionsstapel erstellt werden kann.
  • Da das Erstellungsdatum Teil des Dateipfads ist, werden neue Versionen, die nach Mitternacht (UTC) erstellt werden, möglicherweise nicht korrekt angeordnet, es sei denn, Sie geben einen Versatz für den Erstellungszeitpunkt des ursprünglichen Uploads an.

Dieser zweite Punkt ist wichtig.Angenommen, 48 Stunden nach dem ersten Upload wird eine neue Version des Assets erstellt.Um das Bild mit dem Originalbild zu stapeln, müssen wir einen Versatz von 48 Stunden in die Vergangenheit angeben: 172.800 Sekunden.

${
>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

Wäre das aktuelle Asset ursprünglich in den Ordner 2022_04_03 hochgeladen worden, wird es nun in den Ordner 2022_04_01 hochgeladen und mit dem richtigen Asset zusammengeführt.

Als Nächstes

Dies ist der letzte Leitfaden für die Erstellung einer großartigen C2C-Integration.Sie können stolz auf sich sein!Wenn Sie wollen, holen Sie sich einen Snack.Jetzt müssen Sie nur noch die Checkliste für Integratoren durchgehen, in der Sie eine Übersicht über alles finden, was für eine absolut zuverlässige Integration erforderlich ist.

Falls Sie dies noch nicht getan haben, empfehlen wir Ihnen, sich an unser Team zu wenden und anschließend mit dem nächsten Leitfaden fortzufahren.Wir freuen uns darauf, von Ihnen zu hören!