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.

Usar acesso baseado em tempo

Neste guia de início rápido, você vai receber um token OAuth para sua conta e enviar solicitações recorrentes aos endpoints da API Data Portability.

Este guia de início rápido aborda como usar a API Data Portability para acesso baseado em tempo aos dados do usuário. Para acesso único aos dados do usuário, consulte Começar a usar a API Data Portability. Para saber como aplicar filtros de tempo à sua solicitação, consulte Aplicar filtros de tempo.

Conteúdo do laboratório

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

Envie uma solicitação autenticada para o endpoint InitiatePortabilityArchive fornecendo um token OAuth válido. A resposta precisa conter um job_id válido.
Envie uma solicitação autenticada para o endpoint GetPortabilityArchiveState. A resposta precisa conter um estado de job válido e, quando o job for concluído, um URL assinado.
Envie uma solicitação autenticada com um token OAuth válido para o endpoint InitiatePortabilityArchive uma segunda vez usando as mesmas credenciais. Isso retorna um erro FAILED_PRECONDITION quando a solicitação é feita em até 24 horas após a solicitação inicial.

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 tempo de acesso, selecione 30 dias para testar o acesso baseado em tempo.
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ê também pode usar o escopo de atividade do YouTube ou os dois.

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.
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 Data Portability. Esses comandos exigem o token OAuth e a chave da API que você coletou anteriormente.

Para chamar a API Data Portability:

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

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 precisa conter apenas os escopos do OAuth que receberam acesso. Neste exemplo, apenas myactivity.search foi concedido. Se você incluir outros grupos de recursos, um erro será retornado. Para mais detalhes, consulte Restrições de escopo.

A solicitação InitiatePortabilityArchive retorna uma job_id 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>"
  "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/portabilityArchiveState
```
Faça o seguinte:
- your_OAuth_token é seu token OAuth.
- your_job_id é 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.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
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.

Repita o comando anterior para enviar uma solicitação autenticada para o endpoint InitiatePortabilityArchive.

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.

A resposta deve indicar que você já exportou o recurso myactivity.search e um carimbo de data/hora para quando você puder tentar novamente.

...
  "error": {
    "code": 429,
    "message": "Requested resources have already been exported. You can initiate another export after #{timestamp_after_24hrs}.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_TIME_BASED",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "#{previous_job_ids}"
    "access_type": "ACCESS_TYPE_TIME_BASED"
    "timestamp_after_24hrs": "#{timestamp_after_24hrs}"
...