Graph API

API de Carregamento Retomável

A API de Carregamento Retomável permite que você carregue grandes arquivos na Graph API e retome as sessões de carregamento sem precisar reiniciar o processo. Depois de carregar os arquivos, é possível usar os respectivos identificadores em outros pontos de extremidade da Graph API compatíveis.

Vale lembrar que o uso da API de Carregamento Retomável não é a única forma de carregar arquivos. Diversos nós têm bordas compatíveis com carregamento. Entretanto, a maioria deles não consegue gerenciar grandes arquivos nem retomar uma sessão de carregamento interrompida.

As referências de pontos de extremidade que aceitam identificadores de arquivo carregado indicarão se os identificadores retornados pela API de Carregamento Retomável são compatíveis.

Etapas de carregamento

São necessárias duas etapas para carregar um arquivo:

  1. Use o ponto de extremidade de carregamentos do aplicativo para descrever o arquivo e criar uma sessão de carregamento.
  2. Use o ID da sessão de carregamento retornado para iniciar o processo.

Se tudo correr bem, um identificador será retornado. Use-o em outros pontos de extremidade que aceitam identificadores de arquivo retornados pela API de Carregamento Retomável.

Etapa 1: criar uma sessão

Envie uma solicitação POST que descreva o arquivo ao ponto de extremidade de carregamentos do aplicativo ({app-id}/uploads) . Se o processo for bem-sucedido, um ID da sessão de carregamento será retornado. Use-o na próxima etapa para iniciar o carregamento.

Sintaxe da solicitação

POST https://graph.facebook.com/{api-version}/{app-id}/uploads
  &file_length={file-length}
  &file_type={file-type}
  &access_token={access-token}

Espaços reservados para parâmetros:

  • {api-version}: a versão da Graph API.
  • {app-id}: o ID do aplicativo. O arquivo carregado que será associado ao app. O usuário precisa ter a função de administrador ou desenvolvedor no app.
  • file-length: o tamanho do arquivo em bytes.
  • file-type: o tipo MIME do arquivo. Valores aceitos: application/pdf, image/jpeg, image/jpg, image/png e video/mp4.
  • {access-token}: o token de acesso do usuário do app.

Consulte a referência do ponto de extremidade de carregamentos do aplicativo para ver a lista completa de parâmetros de consulta disponíveis e tipos de arquivos compatíveis.

Resposta

{
  "id": "{id}"
}

Valores da propriedade de resposta:

  • {id}: o ID da sessão de carregamento.

Exemplo de solicitação

curl -X POST \
 "https://graph.facebook.com/v19.0/584544743160774/uploads?file_length=109981&file_type=image/png&access_token=EAAIT..."

Exemplo de resposta

{
    "id": "upload:MTphd..."
}

Etapa 2: iniciar o carregamento

Inicie a sessão de carregamento enviando uma solicitação POST ao endereço do host da Graph API e inclua o {id} da sessão com os cabeçalhos obrigatórios a seguir. Se o processo for bem-sucedido, um identificador de arquivo {h} será retornado. Use-o nos pontos de extremidade da Graph API que aceitam identificadores de arquivo retornados pela API de Carregamento Retornável.

Caso a sessão de carregamento esteja demorando mais que o esperado ou tenha sido interrompida, siga as etapas descritas na seção Interrupções.

Sintaxe da solicitação

POST https://graph.facebook.com/{api-version}/{upload-session-id}
  --header 'Authorization: OAuth {access-token}' 
  --header 'file_offset: 0'
  --data-binary @{file-name}

Valores de espaço reservado

  • {api-version}: a versão da Graph API.
  • {upload-session-id}: o ID da sessão de carregamento (retornado na etapa 1).
  • {access-token}: o token de acesso do usuário do app. O usuário precisa ter uma função no app da etapa 1.
  • {file-name}: o nome do arquivo a ser carregado.

É preciso incluir o token de acesso no cabeçalho. Caso contrário, a sua solicitação falhará.

Resposta

{
  "h": "{h}"
}

Valores da propriedade de resposta:

  • {h}: o identificador do arquivo carregado.

Exemplo de solicitação

curl -X POST \
 "https://graph.facebook.com/v19.0/upload:MTphd..." \
 --header "Authorization: OAuth EAAIT..." \
 --header "file_offset: 0" \
 --data-binary @cats_are_jerks.png

Exemplo de resposta

{
    "h": "2:c2FtcGxl..."
}

Interrupções

Caso a sessão de carregamento esteja demorando mais que o esperado ou tenha sido interrompida, envie uma solicitação GET ao endereço de host da Graph API e inclua o ID da sessão. A API retorna um valor file_offset que pode ser usado para retomar o processo de carregamento do ponto em que parou.

Sintaxe da solicitação

GET https://graph.facebook.com/{api-version}/{upload-session-id}
  ?access_token={access-token}

Valores de espaço reservado:

  • {api-version}: a versão da Graph API.
  • {upload-session-id}: o ID da sessão de carregamento (retornado na Etapa 1: criar uma sessão.
  • {access-token}: o token de acesso do usuário do app.

Resposta

{
  "id": "{id}",
  "file_offset": {file-offset}
}

Valores da propriedade de resposta:

  • {id}: o ID da sessão de carregamento que foi consultado.
  • {file-offset}: um número inteiro que indica a quantidade de bytes carregados.

Guarde o valor file_offset e repita a Etapa 2: iniciar o carregamento, atribuindo o valor ao cabeçalho file_offset correspondente. Com isso, o processo de carregamento será retomado do ponto em que parou.

Exemplo de solicitação

curl -X GET \
 "https://graph.facebook.com/v19.0/upload:MTphd...&access_token=EAAIT..." \

Exemplo de resposta

{
  "id": "upload:MTphd",
  "file_offset": 5238
}