Transmitir alterações da Assembly em tempo real

Transmite as alterações de status da Assembly como Server-Sent Events.

Na resposta após criar uma Assembly, você encontrará dois campos para consultar o Assembly Status: assembly_ssl_url e update_stream_url. Você pode consultar o Assembly Status atual pela URL fornecida em assembly_ssl_url. Para obter informações sobre o andamento da Assembly, você pode consultar essa URL periodicamente ou se inscrever no fluxo de atualizações descrito neste documento.

Eventos enviados pelo servidor

A propriedade update_stream_url no Assembly Status define uma URL em que o fluxo de atualizações da Assembly correspondente está disponível por meio de eventos enviados pelo servidor.

Eventos enviados pelo servidor⁠ são uma tecnologia web para enviar notificações em tempo real do servidor para um cliente por HTTP. Essa tecnologia é semelhante a Web Sockets, mas permite apenas mensagens unidirecionais do servidor para o cliente e consiste em um formato simples baseado em texto⁠.

Enquanto a Assembly estiver no estado de upload ou de execução, um cliente poderá se conectar a este endpoint enviando uma requisição GET com o campo de cabeçalho Accept: text/event-stream para a URL especificada em update_stream_url e analisar o fluxo da resposta. O servidor pode enviar uma combinação de mensagens e eventos para o cliente. A diferença entre eles é que os eventos incluem um payload adicional com informações, enquanto as mensagens não.

Vários clientes podem se inscrever na mesma Assembly. Fechar uma conexão mantém as outras conectadas. Durante o desligamento do componente de upload, os fluxos existentes são fechados e novas conexões recebem uma resposta HTTP 503 vazia. Consulte o Assembly Status atual para verificar se o processamento terminou.

Mensagens

Uma mensagem consiste no nome da mensagem, sem nenhum payload adicional. Na transmissão, uma mensagem com o nome assembly_finished tem esta aparência ([NL] indica uma nova linha):

data: assembly_finished[NL]
[NL]

A Transloadit envia as seguintes mensagens:

• assembly_upload_meta_data_extracted é emitida quando todos os uploads são concluídos e os metadados de todos eles foram extraídos.
• assembly_uploading_finished é emitida quando todos os uploads desta Assembly foram concluídos e a Assembly passa do estado de upload para o estado de execução.
• assembly_finished é emitida quando a Assembly termina, o que não significa necessariamente que o processamento tenha sido bem-sucedido. Ela também é enviada após o cancelamento ou ao se conectar a uma Assembly já encerrada, inclusive uma que tenha falhado. O servidor encerra o fluxo após essa mensagem. Consulte assembly_ssl_url e inspecione o status final: ok: "ASSEMBLY_COMPLETED" indica sucesso, ok: "ASSEMBLY_CANCELED" indica cancelamento e error indica falha.
• ping é emitida periodicamente para manter a conexão ativa enquanto a Assembly está sendo processada. Atualmente, ela é enviada a cada minuto, embora esse intervalo possa mudar no futuro.

Eventos

Um evento consiste no nome do evento e em um payload adicional. Na transmissão, um evento com o nome assembly_result_finished tem esta aparência ([NL] indica uma nova linha):

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

A Transloadit envia os seguintes eventos:

• assembly_error é emitido quando ocorre um erro durante a execução da Assembly. O servidor encerrará o fluxo após esse evento. Informações adicionais sobre o erro são incluídas, por exemplo:

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

• assembly_upload_finished é emitido para cada upload concluído. Informações adicionais sobre o arquivo enviado são incluídas. A estrutura é a mesma de um objeto no array uploads do Assembly Status, por exemplo:

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

• assembly_result_finished é emitido sempre que um novo resultado de um Step está disponível. O payload é uma tupla [stepName, file]. O objeto do arquivo tem a mesma estrutura de uma entrada em results[stepName] do Assembly Status, por exemplo:

  [
    "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 é emitido em intervalos regulares com informações sobre o Execution Progress geral da Assembly e de seus arquivos. A estrutura e os mecanismos são detalhados em Assembly Execution Progress, por exemplo:

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

  Observação: progress_per_original_file usa original_id como chave. Arquivos importados sem um original_id não aparecerão nesta lista.

O fluxo não reenvia eventos anteriores. Em particular, um listener de assembly_error não pode informar um erro que ocorreu antes de você se conectar. Quando a Assembly deixa de estar na memória do componente de upload, a URL do fluxo retorna HTTP 404. Em caso de desconexão ou de indisponibilidade do fluxo, consulte assembly_ssl_url; se a Assembly ainda estiver no estado de upload ou de execução, continue consultando essa URL periodicamente. O fechamento do fluxo, por si só, não comprova o sucesso.

Exemplo em JavaScript

Navegadores modernos oferecem suporte nativo a eventos enviados pelo servidor por meio do construtor EventSource. Supondo que o Assembly Status esteja armazenado na variável assembly_status, o cliente pode escutar a mensagem assembly_finished, a mensagem assembly_uploading_finished e o evento assembly_result_finished da seguinte forma: Se o fluxo for desconectado, este exemplo passa a consultar o status a cada dois segundos até que a Assembly atinja um status final. Falhas HTTP ou de rede são reportadas em vez de serem tratadas como sucesso.

const stream = new EventSource(assembly_status.update_stream_url)
const activeStatuses = ["ASSEMBLY_UPLOADING","ASSEMBLY_EXECUTING","ASSEMBLY_REPLAYING"]
let pollingStarted = false

async function checkAssemblyStatus() {
  while (true) {
    const response = await fetch(assembly_status.assembly_ssl_url)
    if (!response.ok) {
      throw new Error(`Assembly status request failed: ${response.status}`)
    }
    const status = await response.json()
    if (status.error) {
      console.error('Assembly failed', status.error)
      return
    }
    if (status.ok === 'ASSEMBLY_COMPLETED') {
      console.log('Assembly completed', status.results)
      return
    }
    if (status.ok === 'ASSEMBLY_CANCELED') {
      console.warn('Assembly was canceled')
      return
    }
    if (!activeStatuses.includes(status.ok)) {
      throw new Error(`Assembly did not complete successfully: ${status.ok}`)
    }
    console.log('Assembly is not complete; continue polling its status URL', status.ok)
    await new Promise((resolve) => setTimeout(resolve, 2000))
  }
}

function closeStreamAndCheckStatus() {
  if (pollingStarted) return
  pollingStarted = true
  stream.close()
  checkAssemblyStatus().catch(console.error)
}

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

// Handle terminal Assembly errors without reconnecting the stream
stream.addEventListener('assembly_error', (event) => {
  const error = JSON.parse(event.data)
  console.error('Assembly failed', error)
  closeStreamAndCheckStatus()
})

// Recover from a disconnected or unavailable stream using the status URL
stream.addEventListener('error', closeStreamAndCheckStatus)

// 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)
})

Exemplo de requisição

Defina UPDATE_STREAM_URL com a URL completa de update_stream_url da resposta de criação da Assembly. Não substitua o nome do host dessa URL.

curl --fail-with-body -sS --request GET --no-buffer \
  --url "${UPDATE_STREAM_URL:?Set UPDATE_STREAM_URL}" \
  --header 'accept: text/event-stream'

Nenhum corpo de requisição ou campo adicional é necessário.

Para mais informações sobre o formato da resposta, consulte a documentação da Mozilla sobre server-sent events⁠.