Transloadit

Änderungen einer Assembly live streamen

GET{UPDATE_STREAM_URL}

In der Antwort nach dem Erstellen einer Assembly finden Sie zwei Felder, um den Assembly Status abzurufen: assembly_ssl_url und update_stream_url. Sie können den aktuellen Assembly Status abrufen, indem Sie die in assembly_ssl_url angegebene URL verwenden. Um Informationen zum Fortschritt der Assembly zu erhalten, können Sie diesen Status entweder regelmäßig abfragen oder den in diesem Dokument beschriebenen Update-Stream abonnieren.

Server-Sent Events

Die Eigenschaft update_stream_url im Assembly Status definiert eine URL, unter der der Update-Stream für die entsprechende Assembly über Server-Sent Events verfügbar ist.

Server-Sent Events sind eine Webtechnologie, mit der Live-Benachrichtigungen über HTTP von einem Server an einen Client gesendet werden. Sie ähneln WebSockets, erlauben jedoch nur unidirektionale Nachrichten vom Server an den Client und verwenden ein einfaches, textbasiertes Format.

Während sich die Assembly im Upload- oder Ausführungsstatus befindet, kann ein Client eine Verbindung zu diesem Endpunkt herstellen. Dazu sendet er eine GET-Anfrage mit dem Header-Feld Accept: text/event-stream an die in update_stream_url angegebene URL und parst den Antwort-Stream. Der Server kann eine Mischung aus Nachrichten und Ereignissen an den Client senden. Ereignisse enthalten im Gegensatz zu Nachrichten eine zusätzliche Nutzlast mit Informationen.

Nachrichten

Eine Nachricht besteht aus dem Nachrichtennamen und enthält keine zusätzliche Nutzlast. Über die Verbindung sieht eine Nachricht mit dem Namen assembly_finished wie folgt aus ([NL] kennzeichnet eine neue Zeile):

data: assembly_finished[NL]
[NL]

Transloadit sendet die folgenden Nachrichten:

  • assembly_upload_meta_data_extracted wird ausgegeben, wenn alle Uploads abgeschlossen und die Metadaten für alle Uploads extrahiert wurden.
  • assembly_uploading_finished wird ausgegeben, wenn alle Uploads für diese Assembly abgeschlossen sind und die Assembly vom Upload- in den Ausführungsstatus wechselt.
  • assembly_finished wird ausgegeben, wenn die Assembly abgeschlossen ist und alle Dateien verarbeitet wurden. Nach dieser Nachricht beendet der Server den Stream.
  • ping wird regelmäßig ausgegeben, um die Verbindung während der Verarbeitung der Assembly aufrechtzuerhalten. Die Nachricht wird derzeit jede Minute gesendet, dieses Intervall kann sich jedoch künftig ändern.

Ereignisse

Ein Ereignis besteht aus dem Ereignisnamen und einer zusätzlichen Nutzlast. Über die Verbindung sieht ein Ereignis mit dem Namen assembly_result_finished wie folgt aus ([NL] kennzeichnet eine neue Zeile):

event: assembly_result_finished[NL]
data: {"id":"6bb16f6cd49a44b4ae431f576e016c6d","name":"lesereihe.doc",...}[NL]
[NL]

Transloadit sendet die folgenden Ereignisse:

  • assembly_error wird ausgegeben, wenn bei der Ausführung der Assembly ein Fehler auftritt. Der Server beendet den Stream nach diesem Ereignis. Zusätzliche Informationen zum Fehler sind enthalten, zum Beispiel:

    {
  "error": "DOCUMENT_CONVERT_UNSUPPORTED_CONVERSION",
  "http_code": 400,
  "step": "avatar",
  "previousStep": ":original",
  "worker": "dhor.transloadit.com",
  "msg": "The output format pdf is not supported for the input format pdf. The input format pdf is currently not allowed."
}

  • assembly_upload_finished wird für jeden abgeschlossenen Upload ausgegeben. Zusätzliche Informationen zur hochgeladenen Datei sind enthalten. Die Struktur entspricht der eines Objekts im Array uploads im Assembly Status, zum Beispiel:

    {
  "id": "6bb16f6cd49a44b4ae431f576e016c6d",
  "name": "lesereihe.doc",
  "basename": "lesereihe",
  "ext": "doc",
  "size": 61440,
  "mime": "application/msword",
  "type": null,
  "field": "file",
  "md5hash": "154a9349b8f9111865a07ed0a7050f55",
  // …
}

  • assembly_result_finished wird ausgegeben, sobald ein neues Ergebnis eines Steps verfügbar ist. Der Name des Steps und zusätzliche Informationen zum Ergebnis sind enthalten. Die Struktur entspricht der eines Objekts im Array results im Assembly Status, zum Beispiel:

    [
  "avatar",
  {
    "id": "5789e06b48ad450aa55f9b3721376581",
    "name": "lesereihe.pdf",
    "basename": "lesereihe",
    "ext": "pdf",
    "size": 120456,
    "mime": "application/pdf",
    "type": "pdf",
    "field": "file",
    "md5hash": "e9df77e5ee87e8ec3b4453bcddf191bc",
    "meta": {
      "page_count": 1,
      "width": 1238,
      "height": 1750,
      // …
    },
    // …
  }
]

  • assembly_execution_progress wird in regelmäßigen Abständen mit Informationen zum gesamten Execution Progress der Assembly und ihrer Dateien ausgegeben. Struktur und Mechanismen werden unter Assembly Execution Progress ausführlich beschrieben, zum Beispiel:

    {
  "progress_combined": 50,
  "progress_per_original_file": [
    {
      "original_id": "6bb16f6cd49a44b4ae431f576e016c6d",
      "progress": 50
    }
  ]
}

    Hinweis: progress_per_original_file verwendet original_id als Schlüssel. Importierte Dateien ohne original_id erscheinen nicht in dieser Liste.

Beispiel in JavaScript

Moderne Browser unterstützen Server-Sent Events nativ über den Konstruktor EventSource. Wenn der Assembly Status in der Variable assembly_status gespeichert ist, kann der Client wie folgt auf die Nachricht assembly_finished, die Nachricht assembly_uploading_finished und das Ereignis assembly_result_finished reagieren:

const stream = new EventSource(assembly_status.update_stream_url)

// Listen for the assembly_finished and assembly_uploading_finished messages
stream.addEventListener('message', (event) => {
  switch (event.data) {
    case 'assembly_finished':
      console.log('Assembly is finished')
      break
    case 'assembly_uploading_finished':
      console.log('All uploads are finished')
      break
  }
})

// Listen for the assembly_result_finished event
stream.addEventListener('assembly_result_finished', (event) => {
  const result = JSON.parse(event.data)
  console.log('Assembly result is available', result)
})

GET-Abfragekomponenten

Keine Abfragekomponenten für die Anfrage erforderlich

    Antwort

    Hier sehen Sie ein Beispiel für einen Antworttext:

    data: assembly_uploading_finished

event: assembly_upload_finished
data: {"id":"7354d54e9dfa4a47b0f8c451730038b9","name":"lesereihe.doc","basename":"lesereihe","ext":"doc","size":61440,"mime":"application/msword","type":null,"field":"file","md5hash":"154a9349b8f9111865a07ed0a7050f55", [...]

data: assembly_upload_meta_data_extracted

event: assembly_result_finished
data: ["avatar",{"id":"77d73782d83447c38a87af024e03d329","name":"lesereihe.pdf","basename":"lesereihe","ext":"pdf","size":120456,"mime":"application/pdf","type":"pdf","field":"file","md5hash":"278042dc10ac7a9b583c9467dac8cfda", [...]

event: assembly_execution_progress
data: {"progress_combined":100,"progress_per_original_file":[]}

data: assembly_finished

    Weitere Informationen zum Antwortformat finden Sie in der Mozilla-Dokumentation zu Server-Sent Events.