Os novos recursos da API Data Portability estão sendo lançados agora e vão estar disponíveis para todos até 20 de fevereiro de 2025.

Esta página foi traduzida pela API Cloud Translation.

Aplicar filtros de tempo às suas solicitações

Neste guia de início rápido, você vai receber um token OAuth para sua conta e enviar solicitações aos endpoints da API Data Portability usando carimbos de data/hora para filtrar os dados exportados.

Este guia de início rápido aborda como usar a API Data Portability com acesso baseado em tempo e aplicar filtros de tempo para recursos com suporte. Para mais detalhes sobre o acesso por tempo aos dados do usuário, consulte Usar o acesso por tempo.

Conteúdo do laboratório

Neste guia de início rápido, você vai aprender a:

Envie solicitações autenticadas recorrentes para o endpoint InitiatePortabilityArchive para exportar apenas os novos dados desde a última exportação.
Envie uma solicitação autenticada para o endpoint InitiatePortabilityArchive para exportar apenas dados dos últimos seis meses.
Envie uma solicitação autenticada para o endpoint InitiatePortabilityArchive para exportar apenas dados de um período específico.

Pré-requisitos

Para executar este guia de início rápido, você precisa:

Verifique se a API Data Portability está disponível para os usuários na sua região. Para conferir uma lista de países e regiões com suporte, consulte as Perguntas frequentes na página "Compartilhar uma cópia dos seus dados com terceiros".
Conclua as etapas de configuração da API Data Portability.
Siga as etapas para configurar o OAuth para apps da Web em JavaScript. Na produção, normalmente é usado um fluxo diferente, como o fluxo OAuth para aplicativos de servidor da Web. Para simplificar, este guia de início rápido usa o fluxo do app da Web JavaScript.
- Ao criar suas credenciais de autorização, anote o ID do cliente OAuth 2.0 e o URI de redirecionamento autorizado (por exemplo, https://google.com). Você vai precisar deles mais tarde no guia de início rápido.
- Ao configurar escopos para a API Data Portability, observe que este guia de início rápido usa o grupo de recursos myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Ao escolher o período de acesso, selecione 30 dias para testar a filtragem de tempo com o acesso baseado em tempo. Os filtros de tempo também funcionam com o acesso único.
Receba um token OAuth.
Ter acesso a uma conta que pertence ou é controlada pela sua organização. Os dados de atividade de pesquisa dessa conta são exportados neste guia de início rápido.

Receber um token OAuth

Neste guia de início rápido, você vai enviar uma solicitação de autorização para receber um token OAuth usando um URL. Esse processo usa o fluxo para apps da Web em JavaScript. Esse fluxo não retorna um token de atualização.

Para um app de produção, normalmente você usa um fluxo OAuth para receber um token de atualização que pode ser usado para gerar tokens de acesso sob demanda. Um exemplo disso seria o fluxo de apps da Web do lado do servidor.

Para conseguir um token OAuth:

Crie um URL como este.
```
https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=token&
scope=https://www.googleapis.com/auth/dataportability.myactivity.search&
state=developer-specified-value
```
No URL:
- client_id é o ID do cliente OAuth.
- redirect_uri é o URI de redirecionamento autorizado. Por exemplo, https://google.com.
O escopo usado no URL deste guia de início rápido é o escopo da atividade de pesquisa. Você pode usar qualquer escopo compatível com filtros de tempo.

Aviso: não misture escopos da API de portabilidade de dados com outros tipos de escopos, use muitos escopos de uma só vez ou inclua escopos concedidos anteriormente, porque isso resulta em erros. Para saber mais, consulte Restrições de escopo.
Cole o URL na barra de endereço do navegador e siga as etapas no fluxo do OAuth. Esse fluxo exige que você faça login na conta que pertence ou é controlada pela sua organização e que está sendo usada neste guia de início rápido.

Essa é a conta que está consentindo com os escopos do OAuth. A tela de consentimento deve ser semelhante a esta (o texto na tela pode variar do texto nesta imagem):
Escolha os escopos para conceder acesso e o período de compartilhamento dos dados da conta (uma vez, 30 dias ou 180 dias). Para este guia de início rápido, escolha 30 dias. Os filtros de tempo também funcionam com o acesso único.
Depois de conceder o consentimento e decidir a duração do acesso, você será redirecionado para o URI de redirecionamento: https://google.com. O URL gerado na barra de endereço inclui o token de acesso OAuth.

Por exemplo, se a conta de usuário conceder acesso OAuth ao escopo dataportability.myactivity.search, o URL gerado será parecido com este:
```
https://google.com/#state=developer-specified-value&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
No URL, your_OAuth_token é uma string que representa o token.

Importante: seu token de acesso do OAuth expira em uma hora. Se você precisar gerar um novo token, siga as etapas anteriores.
Para validar o token OAuth, cole este URL no navegador:
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
A resposta será semelhante a esta:
```
{
  "azp": <your_azp_value>,
  "aud": <your_aud_value>,
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "exp": "1694210968",
  "expires_in": "3334",
  "access_type": "online"
}
```
Não é necessário usar os campos azp ou aud para fazer solicitações. O campo azp representa o client_id do apresentador autorizado, e o campo aud identifica o público-alvo desse token, que será igual a um dos IDs de cliente do seu app.

Observação: também é possível verificar o token emitindo uma solicitação HTTP GET.
Colete o token OAuth e a chave de API. Você precisa deles para fazer chamadas para a API Data Portability.

Enviar solicitações para os endpoints

Neste guia de início rápido, você usa comandos curl para chamar os endpoints da API de portabilidade de dados com carimbos de data/hora para filtrar os dados exportados.Esses comandos exigem o token OAuth e a chave de API coletados anteriormente.

Dados da última exportação

Você pode usar filtros de tempo com acesso baseado em tempo para exportar os novos dados desde a última exportação. Por exemplo, considere o escopo https://www.googleapis.com/auth/dataportability.myactivity.search.

Primeiro, você envia uma solicitação autenticada para o endpoint InitiatePortabilityArchive. Essa solicitação inicia um job de arquivamento para o corpus de dados completo.

Execute o seguinte comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"]}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Faça o seguinte:
- your_OAuth_token é seu token OAuth.
Aviso: o parâmetro resources só pode conter os escopos OAuth que receberam acesso e que oferecem suporte a filtros de tempo. Neste exemplo, apenas myactivity.search foi concedido. Se você incluir outros grupos de recursos ou grupos de recursos sem suporte, um erro será retornado. Para saber mais, consulte Restrições de escopo.

A solicitação InitiatePortabilityArchive retorna um archiveJobId e accessType. O ID do job é usado para recuperar o estado do arquivo de dados, e o tipo de acesso determina se você recebeu acesso único ou baseado em tempo aos dados. Para o acesso por tempo, você vai encontrar:
```
{
  "archiveJobId": "<your_job_id_1>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Se você não fornecer um token OAuth válido, esta mensagem de erro será retornada:
```
Request had invalid authentication credentials. Expected OAuth 2.0 access
token, login cookie or other valid authentication credential. See
https://developers.google.com/identity/sign-in/web/devconsole-project.
```
Em seguida, envie uma solicitação autenticada para o endpoint GetPortabilityArchiveState para recuperar o status do job de arquivamento.

Execute o seguinte comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/your_job_id_1/portabilityArchiveState
```
Faça o seguinte:
- your_OAuth_token é seu token OAuth.
- your_job_id_1 é o ID do job retornado pela solicitação InitiatePortabilityArchive.
A resposta é baseada no estado do job. Se o job não estiver concluído, a resposta vai fornecer o estado atual. Envie solicitações para esse endpoint periodicamente até que o job seja concluído.
```
{
  "state": "IN_PROGRESS"
}
```
Se o job estiver concluído, a resposta conterá o estado e um ou mais URLs assinados que são usados para fazer o download do arquivo de dados. Há também um campo export_time que representa o carimbo de data/hora quando a primeira chamada para InitiatePortabilityArchive foi feita.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
  "export_time": "<timestamp_of_first_initiate_request>"
}
```
Cole o URL assinado no navegador para fazer o download do arquivo de dados. Examine o conteúdo do arquivo para garantir que ele contenha os dados de atividade de pesquisa esperados.

Observação: o tempo necessário para concluir o job de arquivamento depende do tamanho do arquivo. A duração máxima é de sete dias.

Se você receber um estado FAILED na resposta, tente fazer a exportação novamente usando o método RetryPortabilityArchive.
Aguarde pelo menos 24 horas e faça outra solicitação para InitiatePortabilityArchive usando o mesmo comando da etapa 1, mas desta vez use o export_time como start_time.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": timestamp_of_first_initiate_request}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate
```
Observação: é possível ajustar start_time para que se sobreponha um pouco a export_time e garantir que todos os dados gerados entre as solicitações sejam incluídos na exportação.

Para o acesso baseado em tempo, isso vai retornar:
```
{
  "archiveJobId": "<your_job_id_2>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Repita a etapa 2 para enviar uma solicitação autenticada ao endpoint GetPortabilityArchiveState e recuperar o status do job de arquivamento (usando <your_job_id_2>).

Quando o job for concluído, a resposta será:

  {
    "state": "COMPLETE",
    "urls": [
      "signed_urls"
    ],
    "start_time": timestamp_of_first_initiate_request,
    "export_time": timestamp_of_second_initiate_request
  }

Verifique se os dados na segunda exportação contêm apenas os novos dados gerados após a primeira exportação.

Dados dos últimos seis meses

Também é possível usar filtros de tempo para exportar apenas os dados mais recentes em vez de todo o corpus.

Suponha que hoje seja 2024-10-01 e que você queira exportar os últimos 6 meses de dados. Primeiro, você envia uma solicitação autenticada para o endpoint InitiatePortabilityArchive com um start_time de "2024-04-01T00:00:00Z".

Execute o seguinte comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2024-04-01T00:00:00Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Para o acesso baseado em tempo, isso vai retornar:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Faça uma solicitação para o endpoint GetPortabilityArchiveState para extrair o status do job de arquivamento.

Execute o seguinte comando curl:
```
curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState
```
Quando o job for concluído, a resposta será:
```
{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2024-04-01T00:00:00Z",
  "export_time": "2024-10-01T00:00:00Z"
}
```
O start_time é o start_time especificado na etapa 1, e o export_time é o carimbo de data/hora quando a chamada para InitiatePortabilityArchive foi feita na etapa 1.
Verifique se a exportação contém apenas dados dos últimos seis meses.

Dados de um período específico

É possível usar filtros de tempo para exportar dados de um intervalo específico de datas, como apenas os dados de 2023.

Primeiro, você envia uma solicitação autenticada para o endpoint InitiatePortabilityArchive com um start_time de "2023-01-01T00:00:00Z" e um end_time de "2023-12-31T23:59:59Z".

Execute o seguinte comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
--data '{"resources":["myactivity.search"],
"start_time": "2023-01-01T00:00:00Z",
"end_time": "2023-12-31T23:59:59Z"}' \
https://dataportability.googleapis.com/v1/portabilityArchive:initiate

Para o acesso baseado em tempo, isso vai retornar:

{
  "archiveJobId": "job_id_1"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}

Faça uma solicitação para o endpoint GetPortabilityArchiveState para extrair o status do job de arquivamento.

Execute o seguinte comando curl:

curl -H 'Authorization: Bearer your_OAuth_token' -X GET \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/archiveJobs/job_id_1/portabilityArchiveState

Quando o job for concluído, a resposta será:

{
  "state": "COMPLETE",
  "urls": [
    "signed_urls"
  ],
  "start_time": "2023-01-01T00:00:00Z",
  "export_time": "2023-12-31T23:59:59Z"
}

O start_time é o start_time especificado na etapa 1, e o export_time é igual ao end_time fornecido na etapa 1.

Verifique se a exportação contém apenas dados de 2023.

Escopos aceitos

Os seguintes escopos são compatíveis com filtros de tempo:

https://www.googleapis.com/auth/dataportability.myactivity.youtube
https://www.googleapis.com/auth/dataportability.myactivity.maps
https://www.googleapis.com/auth/dataportability.myactivity.search
https://www.googleapis.com/auth/dataportability.myactivity.myadcenter
https://www.googleapis.com/auth/dataportability.myactivity.shopping
https://www.googleapis.com/auth/dataportability.myactivity.play
https://www.googleapis.com/auth/dataportability.chrome.history

Cuidado:as solicitações com filtro de tempo que misturam escopos com e sem suporte resultam em um erro INVALID_ARGUMENT que indica The requested resources do not support time filters.