Comece a usar a API Data Portability

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

Este guia de início rápido aborda como usar a API Data Portability para acesso único aos dados do usuário. Para acesso contínuo aos dados do usuário, consulte Usar o acesso baseado em tempo. Para aprender a 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.
  • (Opcional) 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 RESOURCE_EXHAUSTED e tem como objetivo destacar a importância do endpoint ResetAuthorization.
  • Envie uma solicitação autenticada para o endpoint ResetAuthorization. Essa solicitação revoga todos os escopos do OAuth concedidos pelo usuário.
  • (Opcional) Envie uma solicitação para o endpoint InitiatePortabilityArchive usando o mesmo token OAuth usado anteriormente. A solicitação vai falhar depois que a autorização for redefinida.

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.
    • Quando você escolhe o tempo de acesso, este Guia Rápido usa 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:

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

  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 desta 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 dos dados da conta (uma vez, 30 dias ou 180 dias). Para este guia de início rápido, escolha Apenas uma vez.

  4. Depois de conceder o consentimento e escolher 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 o token de acesso do 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.

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

  6. 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 este guia de início rápido, você precisa ter acesso único.

    {
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}

    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.

  3. (Opcional) 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 precisa indicar que o consentimento único para o recurso myactivity.search foi esgotado para esse usuário.

    ...
"error": {
    "code": 429,
    "message": "Requested resources have already been exported. Please call ResetAuthorization and re-obtain consent before trying again.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RESOURCE_EXHAUSTED_ONE_TIME",
        "domain": "dataportability.googleapis.com"
  "metadata": {
    "previous_job_ids": "{previous_job_ids}"
    "access_type": "ACCESS_TYPE_ONE_TIME"
...

  4. Envie uma solicitação autenticada para o endpoint ResetAuthorization. Essa solicitação revoga todos os escopos OAuth concedidos pelo usuário e permite que você chame InitiatePortabilityArchive para um grupo de recursos que você já usou.

    curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset

    Faça o seguinte:

    • your_OAuth_token é seu token OAuth.

    Esse comando retorna uma resposta vazia.

  5. (Opcional) Depois de redefinir a autorização, envie outra solicitação para o endpoint InitiatePortabilityArchive. Use o mesmo comando curl usado anteriormente.

    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 vai retornar um erro porque o token OAuth fornecido foi revogado.

    ...
  "error": {     
    "code": 401,    
        "message": "Request had invalid authentication credentials. Expected
        OAuth 2 access token, login cookie or other valid authentication
        credential. See https://developers.google.com/identity/sign-in/web/devconsole-project.",
        "status": "UNAUTHENTICATED"
  }