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.

Comienza a usar la API de portabilidad de datos

En esta guía de inicio rápido, obtendrás un token de OAuth para tu cuenta y enviarás solicitudes únicas a los extremos de la API de Portabilidad de datos.

En esta guía de inicio rápido, se explica cómo usar la API de Data Portability para obtener acceso único a los datos del usuario. Para obtener acceso continuo a los datos del usuario, consulta Cómo usar el acceso basado en el tiempo. Para conocer 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.
(Opcional) Envía una solicitud autenticada con un token de OAuth válido al extremo InitiatePortabilityArchive por segunda vez con las mismas credenciales. Esto muestra un error RESOURCE_EXHAUSTED y su objetivo es destacar la importancia del extremo ResetAuthorization.
Envía una solicitud autenticada al extremo ResetAuthorization. Esta solicitud revoca todos los permisos de OAuth otorgados por el usuario.
(Opcional) Envía una solicitud al extremo InitiatePortabilityArchive con el mismo token de OAuth que usaste anteriormente. La solicitud debería fallar después de que se restablezca la autorización.

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 de JavaScript. En producción, por lo general, usarías un flujo diferente, como el flujo de OAuth para aplicaciones de servidor web. Para simplificar, en esta guía de inicio rápido, se usa el flujo de la app web de JavaScript.
- Cuando crees tus credenciales de autorización, toma nota de tu ID de cliente de OAuth 2.0 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 eliges la cantidad de tiempo que quieres permitir el acceso, esta guía de inicio rápido usa el acceso por única vez.
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 de JavaScript. Este flujo no muestra un token de actualización.

En el caso de una app de producción, por lo general, usarías un flujo de OAuth para obtener un token de actualización que se pueda usar para generar tokens de acceso a pedido. Un ejemplo de esto sería el flujo de apps web del servidor.

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=token&
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 alcances 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 Solo una vez.
Después de otorgar el consentimiento y elegir 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 el token de acceso de OAuth.

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&access_token=your_OAuth_token&token_type=Bearer&expires_in=3599&scope=https://www.googleapis.com/auth/dataportability.myactivity.search
```
En la URL, your_OAuth_token es una cadena que representa el token.

Importante: Tu token de acceso de OAuth vencerá en una hora. Si necesitas generar un token nuevo, sigue los pasos anteriores.
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. Para los fines de esta guía de inicio rápido, deberías tener acceso único.
```
{
  'archiveJobId': '<your_job_id>'
  'accessType': 'ACCESS_TYPE_ONE_TIME'
}
```
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 se completó, 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.
Nota: Si recibes un estado FAILED en la respuesta, puedes volver a intentar la exportación con el método RetryPortabilityArchive.

(Opcional) 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 se agotó el consentimiento único para el recurso myactivity.search de este usuario.

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

Envía una solicitud autenticada al extremo ResetAuthorization. Esta solicitud revoca todos los permisos de OAuth otorgados por el usuario y te permite llamar a InitiatePortabilityArchive para un grupo de recursos que ya usaste.
```
curl -H 'Authorization: Bearer your_OAuth_token' -X POST \
-H "Content-Type: application/json; charset=utf-8" \
https://dataportability.googleapis.com/v1/authorization:reset
```
En el comando, haz lo siguiente:
- your_OAuth_token es tu token de OAuth.
Este comando muestra una respuesta vacía.

(Opcional) Después de restablecer la autorización, envía otra solicitud al extremo InitiatePortabilityArchive. Usa el mismo comando curl que usaste 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

En el comando, haz lo siguiente:

your_OAuth_token es tu token de OAuth.

La respuesta debería mostrar un error porque se revocó el token de OAuth que proporcionaste.

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