Chamar métodos da API Data Portability

A API Data Portability consiste nestes métodos:

  • portabilityArchive.initiate
  • archiveJobs.getPortabilityArchiveState
  • resetAuthorization
  • archiveJobs.retryPortabilityArchive
  • archiveJobs.cancelPortabilityArchive
  • accessType.check

portabilityArchive.initiate

Chame o método portabilityArchive.initiate para iniciar um novo job de exportação de dados.

Ao iniciar um job de exportação para criar um arquivo de dados, é necessário solicitar o grupo de recursos apropriado e fornecer um token OAuth com os escopos necessários para esse grupo. O token OAuth é usado para autorizar a solicitação e determinar quais dados do usuário estão sendo exportados.

Para conferir uma lista de todos os grupos de recursos aceitos por um serviço específico, consulte a página de referência do esquema desse serviço.

Por exemplo, se você estiver exportando dados de atividade de pesquisa, chame InitiatePortabilityArchive(resources = ["myactivity.search"]). A solicitação precisa ter um token OAuth anexado com o escopo OAuth de pesquisa: https://www.googleapis.com/auth/dataportability.myactivity.search.

Embora seja possível incluir vários grupos de recursos em uma única chamada InitiatePortabilityArchive, isso não é recomendado. Para acelerar o processamento, faça solicitações InitiatePortabilityArchive separadas para cada grupo de recursos. Quando você solicita vários grupos de recursos, o token OAuth anexado precisa ter todos os escopos apropriados anexados.

Por exemplo, em vez de chamar InitiatePortabilityArchive(resources = ["myactivity.search","myactivity.youtube"]) para criar um arquivo de dados para a pesquisa e a atividade do YouTube, faça estas chamadas separadas: InitiatePortabilityArchive(resources = ["myactivity.search"]) e InitiatePortabilityArchive(resources = ["myactivity.youtube"]).

A solicitação InitiatePortabilityArchive retorna um job_id. Esse ID de job é usado para recuperar o estado do arquivo de dados.

archiveJobs.getPortabilityArchiveState

O método archiveJobs.getPortabilityArchiveState é chamado para recuperar o estado atual do job de exportação de arquivo de dados. Ao chamar getPortabilityArchiveState, você fornece o job_id: GetPortabilityArchiveState(job_id). Você também precisa fornecer um token OAuth com escopos que correspondam aos grupos de recursos usados na solicitação initiate.

Se o estado for COMPLETE, URLs assinados do Cloud Storage serão retornados e poderão ser usados para fazer o download dos dados. Os URLs assinados expiram após seis horas, e os dados ficam disponíveis por 14 dias.

Uma solicitação de arquivamento pode levar vários minutos, várias horas ou até vários dias para ser concluída, dependendo do volume de dados. É possível verificar o estado do arquivo a cada cinco a 60 minutos.

resetAuthorization

O método resetAuthorization faz o seguinte:

  • Revoga todos os escopos OAuth concedidos pelo usuário
  • Permite que o aplicativo chame InitiatePortabilityArchive para um grupo de recursos usado anteriormente.
  • Remove o acesso a arquivos de dados anteriores

Ao chamar resetAuthorization, é necessário fornecer um token OAuth anexado para o usuário cuja autorização você está redefinindo.

archiveJobs.retryPortabilityArchive

O método archiveJobs.retryPortabilityArchive é chamado para tentar novamente jobs com falha em que o método archiveJobs.getPortabilityArchiveState já retornou um estado de FAILED. Isso pode ocorrer devido a uma falha temporária no back-end. Nesse caso, tente novamente a exportação sem receber um novo token OAuth do usuário. Ao chamar retryPortabilityArchive, você fornece o job_id com um token OAuth válido. O endpoint tenta criar uma exportação para os mesmos grupos de recursos solicitados na solicitação initiatePortabilityArchive inicial. Se for bem-sucedido, esse endpoint vai retornar um job_id novo que pode ser usado em chamadas para getPortabilityArchiveState. Um job com falha pode ser tentado de novo até três vezes.

Exemplo:

  1. Você chama InitiatePortabilityArchive(resources = ["myactivity.search"]) e recebe job_id: 0.

  2. Depois de chamar GetPortabilityArchiveState(0), você recebe JobSate: FAILED.

  3. Em seguida, chame RetryPortabilityArchive(0) para receber job_id: 1 para resources = ["myactivity.search"].

  4. Depois, você pode continuar fazendo ligações para GetPortabilityArchiveState(1).

archiveJobs.cancelPortabilityArchive

O método archiveJobs.cancelPortabilityArchive é chamado para cancelar um job individual sem revogar tokens existentes quando você tem acesso contínuo aos dados do usuário. Isso é útil quando um job ou recurso não é mais necessário e você quer redefinir a cota de jobs. O job precisa ser IN_PROGRESS e ter sido criado com acesso baseado em tempo para ser cancelado.

Por exemplo, você pode cancelar um job baseado em tempo em andamento para myactivity.youtube e youtube.public_videos e iniciar um novo job apenas para myactivity.youtube.

accessType.check

O método accessType.check permite verificar se um token OAuth autoriza o acesso baseado em tempo ou único antes de iniciar um job. Por exemplo, você pode exportar o histórico completo de um usuário se ele conceder acesso único ou apenas o último dia se ele conceder acesso por tempo.

A resposta contém dois campos: listas de IDs de grupo de recursos de portabilidade de dados únicos e baseados em tempo autorizados pelo token OAuth usado na solicitação. Os usuários não podem misturar tipos de acesso em uma concessão de token, mas não é necessário assumir esse comportamento no futuro.