Esta página foi traduzida pela API Cloud Translation.

Comece a usar a API Data Portability

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

Conteúdo do laboratório

Neste guia de início rápido, você aprenderá a fazer o seguinte:

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 ao 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 pela 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 ao endpoint ResetAuthorization. Essa solicitação revoga todos os escopos OAuth concedidos pelo usuário.
(Opcional) Envie uma solicitação para o endpoint InitiatePortabilityArchive usando o mesmo token OAuth usado anteriormente. A solicitação deve falhar após a redefinição da autorização.

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 no seu local. Para acessar uma lista de países e regiões compatíveis, consulte as Perguntas comuns na página "Compartilhar uma cópia dos seus dados com um terceiro".
Conclua as etapas de configuração da API Data Portability.
Siga as etapas para configurar o OAuth para apps da Web JavaScript. Na produção, normalmente você usa um fluxo diferente, como o fluxo do 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 adiante no guia de início rápido.
- Quando você configura escopos da API Data Portability, este guia de início rápido usa o grupo de recursos myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
Consiga um token OAuth.
ter acesso a uma conta da sua organização ou controlada por ela. Os dados da atividade de pesquisa desta conta são exportados neste guia de início rápido.

Receber um token OAuth

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

Em um app de produção, você normalmente usaria 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 para apps da Web do lado do servidor.

Para receber um token OAuth:

Escreva um URL como o seguinte.
```
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&
include_granted_scopes=true&
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. Também é possível usar o escopo de atividade do YouTube ou ambos.
Cole o URL na barra de endereço do navegador e siga as etapas no fluxo do OAuth. Para este fluxo, é necessário fazer login na conta de propriedade ou controlada pela sua organização usada para este guia de início rápido.

Essa é a conta que consente com os escopos do OAuth. A tela de consentimento será semelhante a esta (o texto exibido pode ser diferente do texto desta imagem):
Depois de conceder o consentimento, você será encaminhado 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 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 seu 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"
}

Reúna o token OAuth e a chave de API. Você vai precisar deles para fazer chamadas para a API Data Portability.

Enviar solicitações para os endpoints

Neste guia de início rápido, você vai usar comandos curl para chamar os endpoints da API Data Portability. Esses comandos exigem o token OAuth e a chave de API que você coletou anteriormente.

Para chamar a API Data Portability:

Primeiro, você envia uma solicitação autenticada para o endpoint InitiatePortabilityArchive. Esta 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.
OBSERVAÇÃO: o parâmetro resources precisa conter apenas os escopos OAuth que receberam acesso. Neste exemplo, apenas myactivity.search foi concedido. Se você incluir outros grupos de recursos, um erro será retornado.

A solicitação InitiatePortabilityArchive retorna um job_id. Esse ID do job é usado para recuperar o estado do arquivo de dados.
```
{
  "archiveJobId": "<your_job_id>"
}
```
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, você enviará uma solicitação autenticada ao 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 state do job. Se o job não estiver concluído, a resposta 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 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 tenha os dados da atividade de pesquisa esperado.

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.
Observação :se você receber um estado FAILED na resposta, tente exportar novamente usando o método RetryPortabilityArchive.

(Opcional) Repita o comando anterior para enviar uma solicitação autenticada ao 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 o usuário em questão.

...
  "error":
    {
      "code": 429,
  "message": "Resource has been exhausted (check quota).",
  "status": "RESOURCE_EXHAUSTED"
}

Envie uma solicitação autenticada ao endpoint ResetAuthorization. Essa solicitação revoga todos os escopos OAuth concedidos pelo usuário e permite chamar 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.

(Opcional) Depois de redefinir a autorização, envie outra solicitação para o endpoint InitiatePortabilityArchive. Use o mesmo comando curl que você usou 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 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"
  }