Importa datos a Google Chat

Con la API de Google Chat, puedes importar datos de otras plataformas de mensajería a Google Chat. Puedes importar mensajes, archivos adjuntos, reacciones, membresías y entidades de espacios existentes desde otras plataformas de mensajería a los recursos de la API de Chat correspondientes. Para importar estos datos, puedes crear espacios de Chat en modo de importación y, luego, importar los datos a esos espacios. Una vez que se complete el proceso, estos espacios se convertirán en espacios de Chat estándar.

A continuación, se describe el proceso de importación completo:

1. Planifica tu importación
2. Configura la autorización para la app de Chat
3. Cómo crear un espacio en el modo de importación
4. Importa recursos
5. Valida los recursos importados
6. Cómo conciliar las diferencias de recursos importados con los datos de origen
7. Modo de importación completa
8. Otorga acceso al espacio después del modo de importación
9. Solución de problemas

Requisitos previos

Planifica tu importación

Planifica en consecuencia la cantidad de datos que se importarán, comprende cómo los límites y las cuotas de uso pueden afectar el proceso de importación y ten en cuenta los tipos de espacios de Chat admitidos cuando importes datos a un espacio nuevo. Si eres administrador, lee Importa datos de mensajes a Google Chat desde otro servicio y sigue los pasos con atención.

Revisa los límites de uso de la API

El tiempo necesario para importar datos a Chat puede variar mucho según la cantidad de recursos de Chat que se importen. Revisa los límites de uso de tu app de Chat y la cantidad de datos programados para la importación desde la plataforma de mensajería de origen para determinar un cronograma estimado.

Cuando importes mensajes a un espacio, te recomendamos que distribuyas las llamadas al método messages.create() en diferentes subprocesos de mensajes.

Identifica los espacios admitidos para importar

El modo de importación solo admite el SpaceType de SPACE y GROUP_CHAT. No admite DIRECT_MESSAGE. Consulta la documentación de SpaceType para obtener más información.

Crea un espacio en el modo de importación

Para crear un espacio en el modo de importación, llama al método create en el recurso Space y configura importMode como true.

Cuando crees el espacio en el modo de importación, ten en cuenta lo siguiente.

• La fecha y la hora: Recuerda que el modo de importación debe completarse en un plazo de 90 días. Si el espacio sigue en modo de importación después de 90 días desde que se llamó al método spaces.create(), se borra automáticamente y se vuelve inaccesible e irrecuperable.
  • Usa el valor del campo importModeExpireTime para hacer un seguimiento del vencimiento del período de 90 días.
  • No uses el valor del campo createTime para hacer un seguimiento del vencimiento del período de 90 días. No siempre es lo mismo que cuando llamas al método spaces.create(). Cuando se usa el modo de importación, el campo createTime se puede establecer en la marca de tiempo histórica en la que se creó el espacio en la fuente para conservar la hora de creación original.
• El nombre del recurso de espacio (name): Es el identificador único que se usa para recuperar información sobre el espacio específico y al que se hace referencia en pasos posteriores cuando se importa contenido al espacio.

Para conservar la fecha y hora de creación de la entidad de espacio equivalente de la plataforma de mensajería de origen, puedes establecer el createTime del espacio. Este createTime debe establecerse en un valor entre el 1 de enero del 2000 y la hora actual.

Para crear un espacio externo en el modo de importación, configura externalUserAllowed como true. Una vez que se complete la importación correctamente, podrás agregar usuarios externos.

En el siguiente ejemplo, se muestra cómo crear un espacio en el modo de importación:

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'DISPLAY_NAME',
      importMode: true,
      createTime: (new Date('January 1, 2000')).toJSON()
  });
  console.log(space.name);
}

"""Create a space in import mode."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

result = (
    service.spaces()
    .create(
        body={
            'spaceType': 'SPACE',
            'displayName': 'DISPLAY_NAME',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

Reemplaza lo siguiente:

• EMAIL: La dirección de correo electrónico de la cuenta de usuario que suplantas con autoridad en todo el dominio.
• DISPLAY_NAME: Es el nombre del espacio creado en el modo de importación. Debe ser un nombre único para el espacio que se muestra a los usuarios de Chat. Te recomendamos que uses el mismo nombre visible que el espacio desde el que importas datos.

Importa recursos

Para importar recursos desde otras plataformas de mensajería, debes crear recursos de Google Chat (como mensajes, reacciones y archivos adjuntos) en el espacio del modo de importación. Cuando creas un recurso en el espacio, especificas datos del recurso relacionado de la plataforma de mensajería desde la que realizas la migración.

Mensajes

Tus apps de Chat pueden importar mensajes con su propia autoridad o en nombre de un usuario a través de la suplantación de identidad. El autor del mensaje se establece en la cuenta de usuario suplantada. Para obtener más información, consulta Autoriza apps de Chat. Para importar un mensaje en un espacio en modo de importación, llama al método create en el recurso Message. Para conservar la hora de creación del mensaje original de la plataforma de mensajería de origen, puedes establecer el createTime del mensaje. Este createTime debe establecerse en un valor entre la hora de creación del espacio que estableciste anteriormente y la hora actual.

Los mensajes en el mismo espacio no pueden contener el mismo createTime, incluso si se borran los mensajes anteriores con esa hora.

Los mensajes que contienen URLs de terceros en espacios en modo de importación no pueden renderizar vistas previas de vínculos en Google Chat.

Cuando creas los mensajes en el modo de importación, los espacios no envían notificaciones ni correos electrónicos a ningún usuario, incluidos los mensajes que contienen menciones de usuarios.

En el siguiente ejemplo, se muestra cómo crear un mensaje en un espacio en modo de importación:

"""Create a message in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = (
    service.spaces()
    .messages()
    .create(
        parent=NAME,
        body={
            'text': 'Hello, world!',
            'createTime': f'{datetime.datetime(2000, 1, 2).isoformat()}Z',
        },
    )
    .execute()
)

print(result)

Reemplaza lo siguiente:

• EMAIL: La dirección de correo electrónico de la cuenta de usuario que suplantas con autoridad en todo el dominio.
• SPACE_NAME: El nombre del espacio creado en el modo de importación.

Reacciones

Tu app de Chat puede importar reacciones a los mensajes con la API de Chat. Para obtener información sobre los métodos de recursos y los tipos de compatibilidad con la autenticación en los espacios del modo de importación, consulta Autoriza apps de Chat.

Archivos adjuntos

Tu app de Chat puede subir archivos adjuntos con la API de Chat. Para obtener información sobre los métodos de recursos y los tipos de compatibilidad con la autenticación en los espacios del modo de importación, consulta Autoriza apps de Chat. Sin embargo, te recomendamos que uses la API de Google Drive para subir archivos adjuntos como archivos de Google Drive y vincular los URIs de los archivos a los mensajes respectivos en los espacios del modo de importación para importar archivos adjuntos desde otras plataformas de mensajería y evitar alcanzar el límite interno de Google Chat para la carga de archivos adjuntos.

Membresías históricas

Las membresías históricas son membresías creadas para usuarios que ya habían abandonado la entidad de espacio original de la plataforma de mensajería de origen, pero deseas conservar sus datos en Chat. Para obtener información sobre cómo agregar miembros nuevos después de que el espacio ya no esté en modo de importación, consulta Crea un recurso de membresía.

En muchos casos, cuando esos miembros históricos están sujetos a una política de retención de datos en Google, te conviene conservar los datos (como los mensajes y las reacciones) creados por las membresías históricas en un espacio antes de importarlos a Chat. Mientras el espacio esté en modo de importación, puedes importar esas membresías históricas al espacio con el método create en el recurso Membership. Para conservar la hora de salida de la membresía histórica, debes establecer el deleteTime de la membresía. Esta hora de salida debe ser precisa, ya que afecta los datos que se retienen para esas membresías. Además, esta deleteTime debe ser posterior a la marca de tiempo de creación del espacio y no debe ser una marca de tiempo futura.

Además de deleteTime, también puedes establecer createTime para conservar la hora de unión original de la membresía histórica. A diferencia de deleteTime, createTime es opcional. Si no se configura, createTime se calcula automáticamente restando 1 microsegundo a deleteTime. Si se configura, createTime debe ser anterior a deleteTime y debe ser posterior o igual a la hora de creación del espacio. Esta información createTime no se usa para determinar la retención de datos y no se muestra en las herramientas de administración, como la Consola del administrador de Google y Google Vault.

Si bien es posible que un usuario pueda unirse a un espacio y abandonarlo de varias maneras en la plataforma de mensajería de origen (a través de invitaciones, uniéndose por su cuenta o siendo agregado por otro usuario), en Chat, todas esas acciones se representan con los campos históricos de membresía createTime y deleteTime como agregados o quitados.

En el siguiente ejemplo, se muestra cómo crear una membresía histórica en un espacio en modo de importación:

"""Create a historical membership in import mode space."""

import datetime

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
USER = 'users/USER_ID'
result = (
    service.spaces()
    .members()
    .create(
        parent=NAME,
        body={
            'createTime': f'{datetime.datetime(2000, 1, 3).isoformat()}Z',
            'deleteTime': f'{datetime.datetime(2000, 1, 4).isoformat()}Z',
            'member': {'name': USER, 'type': 'HUMAN'},
        },
    )
    .execute()
)

print(result)

Reemplaza lo siguiente:

• EMAIL: La dirección de correo electrónico de la cuenta de usuario que suplantas con autoridad en todo el dominio.
• SPACE_NAME: El nombre del espacio creado en el modo de importación.
• USER_ID: Es el ID único del usuario.

Importa recursos en un espacio externo

Solo puedes crear un espacio externo con el modo de importación usando credenciales que pertenezcan a usuarios dentro de tu organización de Workspace. Esto solo se aplica mientras el espacio está en modo de importación. Una vez que el espacio completa el modo de importación, se puede invitar a los usuarios externos a unirse a los espacios importados (consulta la sección de acceso) y sus credenciales se pueden usar para llamar a la API de Chat.

Valida los recursos importados

Tu app de Chat puede leer y validar el contenido de un espacio en modo de importación llamando al método list en el recurso Message. Puedes leer los recursos Reaction y Attachment desde los campos emojiReactionSummaries y attachment de cualquier mensaje devuelto. Las apps de chat solo pueden llamar a este método en nombre de un usuario a través de la suplantación de identidad. Para obtener más información, consulta Cómo autorizar apps de Chat.

Tu app de Chat también puede leer mensajes individuales para la validación llamando al método get en el recurso Message. Las apps de chat solo pueden llamar a este método para leer sus propios mensajes con su propia autoridad. Para obtener más información, consulta Autoriza apps de Chat.

Las apps de chat también pueden enumerar las membresías históricas llamando al método list en el recurso Membership. Después de que el espacio salga del modo de importación, el método list ya no expondrá las membresías históricas. Las apps de chat solo pueden llamar a este método en nombre de un usuario a través de la suplantación. Para obtener más información, consulta Autoriza apps de Chat.

Puedes leer las propiedades de un espacio del modo de importación llamando al método get en el recurso Space. La respuesta también tendrá el campo importModeExpireTime completado, por lo que podrás hacer un seguimiento adecuado del período para completar el proceso de importación. Las apps de chat solo pueden llamar a este método con su propia autoridad. Para obtener más información, consulta Autoriza apps de Chat.

Concilia las diferencias de los recursos importados con los datos de origen

Si algún recurso importado ya no coincide con la entidad original de la plataforma de mensajería fuente debido a cambios en la entidad original durante la importación, las apps de Chat pueden llamar a la API de Chat para modificar el recurso de chat importado. Por ejemplo, si un usuario edita un mensaje en la plataforma de mensajería de origen después de que se creó ese mensaje en Chat, las apps de Chat pueden actualizar el mensaje importado para que refleje el contenido actual del mensaje original.

Mensajes

Para actualizar los campos admitidos en un mensaje de un espacio en modo de importación, llama al método update en el recurso Message. Las apps de chat solo pueden llamar a este método con la misma autoridad que se usó durante la creación inicial del mensaje. Si usaste la suplantación de identidad del usuario durante la creación del mensaje inicial, debes usar el mismo usuario suplantado para actualizar ese mensaje.

Para borrar un mensaje en un espacio en modo de importación, llama al método delete en el recurso Message. Los mensajes en un espacio en modo de importación no necesitan ser borrados por el creador original del mensaje y se pueden borrar suplantando la identidad de cualquier usuario del dominio. Las apps de chat solo pueden borrar sus propios mensajes con su propia autoridad. Para obtener más información, consulta Autoriza apps de Chat.

Reacciones

Para borrar una reacción a un mensaje en un espacio en modo de importación, usa el método delete en el recurso reactions. Para obtener información sobre los métodos de recursos y los tipos de compatibilidad con la autenticación en los espacios del modo de importación, consulta Autoriza apps de Chat.

Archivos adjuntos

Para actualizar los archivos adjuntos de un mensaje en un espacio en modo de importación, usa el método upload en el recurso media. Para obtener información sobre los métodos de recursos y los tipos de autenticación compatibles en los espacios del modo de importación, consulta Autoriza apps de Chat.

Membresías históricas

Para borrar una membresía histórica en un espacio en modo de importación, usa el método delete en el recurso Membership. Después de que un espacio sale del modo de importación, el método delete ya no te permite borrar membresías históricas.

No puedes actualizar una membresía histórica en un espacio en modo de importación. Si quieres corregir una membresía histórica importada de forma incorrecta, primero debes borrarla y, luego, volver a crearla mientras el espacio aún esté en modo de importación.

Espacios

Para actualizar los campos admitidos en un espacio del modo de importación, usa el método patch en el recurso spaces.

Para borrar un espacio del modo de importación, usa el método delete en el recurso spaces.

Para obtener información sobre los métodos de recursos y los tipos de compatibilidad con la autenticación en los espacios del modo de importación, consulta Autoriza apps de Chat.

Modo de importación completa

Antes de llamar al método completeImport, debes asegurarte de que se hayan completado la validación y la reconciliación de las diferencias de recursos. Salir de un espacio en modo de importación es un proceso irreversible que convierte el espacio en modo de importación en un espacio normal. No hay ningún indicador en el chat que atribuya estos espacios a una importación de datos.

Toma nota de la fecha y la hora en que llamas a completeImport, el nombre del recurso del usuario que hizo la llamada y la respuesta que se devolvió. Esto puede ser útil si tienes problemas y debes investigarlos.

Para completar el modo de importación y hacer que el espacio sea accesible para los usuarios, la app de Chat puede llamar al método completeImport en el recurso Space. Las apps de chat solo pueden llamar a este método en nombre de un usuario a través de la suplantación. Para obtener más información, consulta Autoriza apps de Chat. El usuario suplantado se agrega al espacio como administrador del espacio una vez que se completa este método. Se debe llamar a este método dentro de los 90 días posteriores a la llamada inicial al método create.space. Si intentas llamar a este método después de que transcurra el período de 90 días, la llamada fallará porque se borrará el espacio del modo de importación y ya no se podrá acceder a él desde la app de Chat.

El usuario suplantado en el método completeImport no necesita ser el creador del espacio.

No llames a completeImport demasiado cerca de importModeExpireTime, ya que no podemos garantizar que la solicitud llegue antes de importModeExpireTime y podría haber conflictos con el procesamiento de datos en los sistemas que se activan en el momento de la fecha de vencimiento. Te recomendamos que llames al completeImport al menos 30 minutos antes de importModeExpireTime.

En el siguiente ejemplo, se muestra cómo completar el modo de importación:

"""Complete import."""

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Specify required scopes.
SCOPES = [
    'https://www.googleapis.com/auth/chat.import',
]

CREDENTIALS = (
    service_account.Credentials.from_service_account_file('credentials.json')
    .with_scopes(SCOPES)
    .with_subject('EMAIL')
)

# Build a service endpoint for Chat API.
service = build('chat', 'v1', credentials=CREDENTIALS)

NAME = 'spaces/SPACE_NAME'
result = service.spaces().completeImport(name=NAME).execute()

print(result)

Reemplaza lo siguiente:

• EMAIL: La dirección de correo electrónico de la cuenta de usuario que suplantas con autoridad en todo el dominio.
• SPACE_NAME: El nombre del espacio creado en el modo de importación.

Cómo otorgar acceso al espacio después del modo de importación

Para darles a los usuarios de Chat acceso al espacio importado recientemente, las apps de Chat pueden seguir usando el alcance chat.import y la suplantación de identidad del usuario en un plazo de 90 días a partir de la llamada inicial al método create.space() para hacer lo siguiente:

• Agrega miembros al espacio: Llama al método create() en el recurso Membership. Recomendamos que las apps de Chat creen recursos Membership inmediatamente después de que se complete la importación del espacio, de modo que las apps de Chat puedan seguir usando el alcance chat.import y garantizar que todos los miembros importados tengan acceso al espacio. Debes priorizar agregar miembros que puedan estar sujetos a la política de bloqueo de Vault, que permite conservar los mensajes importados incluso si ya no están sujetos a la política de retención.
• Establece un público objetivo: Llama al método update() en el recurso Space. Para obtener información sobre cómo crear y agregar usuarios objetivo, consulta Cómo hacer que un espacio de Google Chat sea detectable para usuarios específicos en una organización de Google Workspace.

Para usar estos métodos con el alcance de chat.import, el usuario suplantado debe ser administrador del espacio.

En el caso de los espacios externos, el método de membresía también permite invitar a usuarios ajenos a tu organización de Workspace.create() Asegúrate de comprender todas las limitaciones conocidas para los usuarios externos.

Solución de problemas

Si tienes problemas para importar espacios de Chat, consulta los siguientes problemas para obtener ayuda. Si recibes una respuesta de error, toma nota de ella (copia y pega el texto en un documento o guarda una captura de pantalla) para futuras referencias y solución de problemas.

Cuando se importa un espacio correctamente, CompleteImportSpace se completa con el estado OK.

No completaste la importación antes de que venciera el plazo de 90 días.

Como se describió anteriormente en Crea un espacio en modo de importación, si el espacio sigue en modo de importación después de 90 días desde el momento en que se llamó al método create, se borra automáticamente y se vuelve inaccesible y no se puede recuperar.

Desafortunadamente, el espacio borrado ya no está disponible ni se puede recuperar, por lo que se debe iniciar de nuevo el proceso de importación.

Si el espacio no se importó porque tiene demasiados datos para importar en el período de 90 días con los límites de uso actuales, divídelo en dos o más espacios más pequeños para archivarlo y vuelve a iniciar el proceso de importación.

Cómo encontrar espacios faltantes

Si no encuentras el nuevo espacio de Chat, revisa la siguiente tabla para ver la respuesta que recibiste de CompleteImportSpace, la explicación y cómo resolver el problema.