Las nuevas funciones de la API de Data Portability se están lanzando ahora y estarán disponibles para todos el 20 de febrero de 2025.

Se usó la API de Cloud Translation para traducir esta página.

Usa el acceso basado en el tiempo

En esta guía de inicio rápido, obtendrás un token de OAuth para tu cuenta y enviarás solicitudes recurrentes a los extremos de la API de Data Portability.

En esta guía de inicio rápido, se explica cómo usar la API de Data Portability para el acceso basado en el tiempo a los datos del usuario. Para obtener acceso único a los datos del usuario, consulta Cómo comenzar a usar la API de Data Portability. Para obtener información sobre cómo aplicar filtros de tiempo a tu solicitud, consulta Cómo aplicar filtros de tiempo.

Qué aprenderá

En esta guía de inicio rápido, aprenderás a hacer lo siguiente:

Proporciona un token de OAuth válido para enviar una solicitud autenticada al extremo InitiatePortabilityArchive. La respuesta debe contener un job_id válido.
Envía una solicitud autenticada al extremo GetPortabilityArchiveState. La respuesta debe contener un estado de trabajo válido y, cuando se complete, una URL firmada.
Envía una solicitud autenticada con un token de OAuth válido al extremo InitiatePortabilityArchive por segunda vez con las mismas credenciales. Se muestra un error FAILED_PRECONDITION cuando la solicitud se realiza dentro de las 24 horas posteriores a la solicitud inicial.

Requisitos previos

Para ejecutar esta guía de inicio rápido, debes hacer lo siguiente:

Verifica que la API de Data Portability esté disponible para los usuarios de tu ubicación. Para obtener una lista de los países y regiones admitidos, consulta Preguntas frecuentes en la página “Cómo compartir una copia de tus datos con un tercero”.
Completa los pasos de configuración de la API de Data Portability.
Sigue los pasos para configurar OAuth para apps web del servidor.
- Cuando crees tus credenciales de autorización, anota tu ID de cliente de OAuth 2.0, tu secreto de cliente y tu URI de redireccionamiento autorizado (por ejemplo, https://google.com). Los necesitarás más adelante en la guía de inicio rápido.
- Cuando configures los permisos para la API de Data Portability, ten en cuenta que esta guía de inicio rápido usa el grupo de recursos myactivity.search: https://www.googleapis.com/auth/dataportability.myactivity.search.
- Cuando elijas la cantidad de tiempo que quieres permitir el acceso, debes seleccionar 30 días para probar el acceso basado en el tiempo.
Obtén un token de OAuth.
Obtener acceso a una cuenta que sea propiedad de tu organización o que esta controle En esta guía de inicio rápido, se exportan los datos de actividad de búsqueda de esta cuenta.

Obtén un token de OAuth

En esta guía de inicio rápido, enviarás una solicitud de autorización para obtener un token de OAuth con una URL. En este proceso, se usa el flujo para apps web del servidor. Este flujo genera un token de actualización que puedes usar para exportaciones posteriores.

Para obtener un token de OAuth, haz lo siguiente:

Compón una URL como la siguiente.
```
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
```
En la URL:
- client_id es tu ID de cliente de OAuth.
- redirect_uri es tu URI de redireccionamiento autorizado, por ejemplo, https://google.com.
Ten en cuenta que el alcance que se usa en la URL de esta guía de inicio rápido es el del alcance de la actividad de búsqueda. También puedes usar el permiso de actividad de YouTube o ambos.

Advertencia: No mezcles los permisos de la API de Portabilidad de datos con otros tipos de permisos, no uses demasiados permisos a la vez ni incluyas permisos otorgados anteriormente, ya que esto generará errores. Para obtener más información, consulta Restricciones de alcance.
Pega la URL en la barra de direcciones del navegador y sigue los pasos del flujo de OAuth. Este flujo requiere que accedas a la cuenta que pertenece o controla tu organización y que usas para esta guía de inicio rápido.

Esta es la cuenta que otorga su consentimiento a los permisos de OAuth. La pantalla de consentimiento debería verse así (el texto de tu pantalla puede variar del texto de esta imagen):
Elige los permisos a los que deseas otorgar acceso y el período durante el que deseas compartir el acceso a los datos de la cuenta (una vez, 30 días o 180 días). Para esta guía de inicio rápido, elige 30 días.
Después de otorgar el consentimiento y decidir la duración del acceso, se te redireccionará al URI de redireccionamiento: https://google.com. La URL que se genera en la barra de direcciones incluye un código de autorización que intercambiarás por un token de OAuth en el siguiente paso.

Por ejemplo, si la cuenta de usuario otorga acceso de OAuth al permiso dataportability.myactivity.search, la URL generada se verá de la siguiente manera:
```
https://google.com/#state=developer-specified-value&code=your_auth_code&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
Para intercambiar un código de autorización por un token de acceso, llama al extremo del token de OAuth con lo siguiente:
```
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'
```
La respuesta debería verse de la siguiente manera:
```
{
  "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
}
```
En la URL, your_OAuth_token es una cadena que representa el token.

El campo refresh_token_expires_in se mide en segundos y refleja si el usuario eligió 30 días (2592000 segundos) o 180 días (15552000 segundos) de acceso. Si tu app tiene un estado de publicación En prueba, en su lugar, tienes 7 días (604,800 segundos) de acceso, independientemente de la selección del usuario.

Importante: Tu token de acceso de OAuth vencerá en una hora. Almacena tu token de actualización para que se pueda intercambiar por tokens de acceso nuevos más adelante.
Para validar el token de OAuth, pega esta URL en tu navegador:
```
https://www.googleapis.com/oauth2/v3/tokeninfo?access_token=your_OAuth_token
```
La respuesta debería verse de la siguiente manera:
```
{
  "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"
}
```
No necesitas los campos azp ni aud para realizar solicitudes. El campo azp representa el client_id del presentador autorizado, y el campo aud identifica el público al que está destinado este token, que será igual a uno de los IDs de cliente de tu aplicación.

Nota: También puedes verificar el token mediante una solicitud HTTP GET.
Obtén tu token de OAuth y tu clave de API. Necesitas estos datos para realizar llamadas a la API de Data Portability.

Envía solicitudes a los extremos

En esta guía de inicio rápido, usarás los comandos curl para llamar a los extremos de la API de Data Portability. Estos comandos requieren el token de OAuth y la clave de API que recopilaste anteriormente.

Para llamar a la API de Data Portability, haz lo siguiente:

Primero, envías una solicitud autenticada al extremo InitiatePortabilityArchive. Esta solicitud inicia un trabajo de archivo.

Ejecuta el siguiente comando de 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
```
En el comando, haz lo siguiente:
- your_OAuth_token es tu token de OAuth.
Advertencia: El parámetro resources solo debe contener los permisos de OAuth a los que se les otorgó acceso. En este ejemplo, solo se otorgó myactivity.search. Si incluyes grupos de recursos adicionales, se mostrará un error. Para obtener más información, consulta Restricciones de alcance.

La solicitud InitiatePortabilityArchive muestra un job_id y un accessType. El ID del trabajo se usa para recuperar el estado del archivo de datos, y el tipo de acceso determina si se te otorgó acceso a los datos de forma única o por tiempo determinado. En el caso del acceso basado en el tiempo, verás lo siguiente:
```
{
  "archiveJobId": "<your_job_id>"
  "accessType": "ACCESS_TYPE_TIME_BASED"
}
```
Si no proporcionas un token OAuth válido, se muestra este mensaje de error:
```
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.
```
A continuación, envías una solicitud autenticada al extremo GetPortabilityArchiveState para recuperar el estado de la tarea de archivo.

Ejecuta el siguiente comando de 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
```
En el comando, haz lo siguiente:
- your_OAuth_token es tu token de OAuth.
- your_job_id es el ID del trabajo que muestra la solicitud InitiatePortabilityArchive.
La respuesta se basa en el estado del trabajo. Si el trabajo no está completo, la respuesta proporciona el estado actual. Debes enviar solicitudes a este extremo de forma periódica hasta que se complete la tarea.
```
{
  "state": "IN_PROGRESS"
}
```
Si la tarea está completa, la respuesta contiene el estado y una o más URLs firmadas que se usan para descargar el archivo de datos.
```
{
  "state": "COMPLETE",
  "urls": [
    "<signed_url>"
  ]
}
```
Pega la URL firmada en tu navegador para descargar el archivo de datos. Debes examinar el contenido del archivo para asegurarte de que contenga los datos de actividad de búsqueda esperados.

Nota: La cantidad de tiempo requerida para completar la tarea de archivo depende del tamaño del archivo. La duración máxima es de siete días.

Si recibes un estado FAILED en la respuesta, puedes volver a intentar la exportación con el método RetryPortabilityArchive.

Repite el comando anterior para enviar una solicitud autenticada al extremo 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

En el comando, haz lo siguiente:

your_OAuth_token es tu token de OAuth.

La respuesta debe indicar que ya exportaste el recurso myactivity.search y una marca de tiempo para cuando puedas volver a intentarlo.

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

Después de 24 horas, puedes solicitar una nueva exportación, pero primero debes intercambiar tu token de actualización por un token de acceso nuevo.

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'

La respuesta debería verse de la siguiente manera:

{
  "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
}

Si el usuario renueva el acceso, el nuevo tiempo de vencimiento se refleja en el campo refresh_token_expires_in.

Puedes usar el nuevo token de acceso para repetir los pasos InitiatePortabilityArchive y GetPortabilityArchiveState.