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 do lado do servidor.
    • Ao criar suas credenciais de autorização, anote o ID do cliente OAuth 2.0, a chave secreta do cliente e o URI de redirecionamento autorizado (por exemplo, https://google.com). Você vai precisar deles mais adiante 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 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 no servidor. Esse fluxo gera um token de atualização que pode ser usado para exportações posteriores.

Para conseguir um token OAuth:

  1. Crie um URL como este.

    https://accounts.google.com/o/oauth2/v2/auth?
client_id=client_id&
redirect_uri=redirect_uri&
response_type=code&
access_type=offline&
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.

  2. 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 vai ficar assim (o texto na tela pode variar do texto nesta imagem):

    Tela de consentimento em que o usuário permite o acesso aos dados da atividade de pesquisa

  3. Escolha os escopos para conceder acesso e o período de compartilhamento de acesso aos dados da conta (uma vez, 30 dias ou 180 dias). Para este guia de início rápido, escolha 30 dias.

  4. Depois de conceder o consentimento e decidir a duração do acesso, você será encaminhado para o URI de redirecionamento: https://google.com. O URL gerado na barra de endereço inclui um código de autorização que você trocará por um token OAuth na próxima etapa.

    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&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search

  5. Para trocar um código de autorização por um token de acesso, chame o endpoint do token OAuth com:

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'code=your_auth_code&\
redirect_uri=redirect_uri\
client_id=client_id&\
client_secret=client_secret&\
grant_type=authorization_code'

    A resposta será semelhante a esta:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token": your_refresh_token,
  "refresh_token_expires_in": 2591999
}

    No URL, your_OAuth_token é uma string que representa o token.

    O campo refresh_token_expires_in está em segundos e reflete se o usuário escolheu 30 dias (259.2000 segundos) ou 180 dias (155.5200 segundos) de acesso. Se o app tiver o status de publicação Em teste, você terá 7 dias (604800 segundos) de acesso, independente da seleção do usuário.

  6. 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.

  7. 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:

  1. 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.

    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.

  2. 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.

    Se você receber um estado FAILED na resposta, tente fazer a exportação novamente usando o método RetryPortabilityArchive.

  3. 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}"
...

  4. Após 24 horas, você pode solicitar uma nova exportação, mas primeiro é necessário trocar o token de atualização por um token de acesso novo.

    curl https://oauth2.googleapis.com/token\
-H 'Content-Type: application/x-www-form-urlencoded' -X POST\
-d 'refresh_token=your_refresh_token&\
client_id=client_id&\
client_secret=client_secret&\
grant_type=refresh_token'

    A resposta será semelhante a esta:

    {
  "access_token": your_OAuth_token,
  "expires_in": 3920,
  "token_type": "Bearer",
  "scope": "https://www.googleapis.com/auth/dataportability.myactivity.search",
  "refresh_token_expires_in": 2505599
}

    Se o usuário renovar o acesso, o novo tempo de expiração será refletido no campo refresh_token_expires_in.

    Você pode usar o novo token de acesso para repetir as etapas InitiatePortabilityArchive e GetPortabilityArchiveState.