Mengimpor data ke Google Chat

Dengan Google Chat API, Anda dapat mengimpor data dari platform pesan lainnya ke Google Chat. Anda dapat mengimpor pesan, lampiran, reaksi, keanggotaan, dan entitas ruang yang ada dari platform pesan lain ke resource Chat API yang sesuai. Anda dapat mengimpor data ini dengan membuat ruang Chat dalam mode impor dan mengimpor data ke ruang tersebut. Setelah proses berhasil diselesaikan, ruang ini akan menjadi ruang Chat standar.

Berikut adalah ringkasan proses impor lengkap:

1. Merencanakan impor
2. Mengonfigurasi otorisasi untuk aplikasi Chat
3. Membuat ruang dalam mode impor
4. Mengimpor aset
5. Memvalidasi resource yang diimpor
6. Menyesuaikan perbedaan resource yang diimpor dari data sumber
7. Mode impor lengkap
8. Memberi akses ke ruang setelah mode impor
9. Pemecahan masalah

Prasyarat

Merencanakan impor

Rencanakan jumlah data yang akan diimpor, pahami pengaruh batas penggunaan dan kuota terhadap proses impor, dan ketahui jenis ruang Chat yang didukung saat mengimpor ke ruang baru. Jika Anda adalah administrator, baca artikel Mengimpor data pesan ke Google Chat dari layanan lain dan ikuti langkah-langkahnya dengan cermat.

Meninjau batas penggunaan API

Waktu yang diperlukan untuk mengimpor data ke Chat dapat sangat bervariasi bergantung pada jumlah resource Chat yang akan diimpor. Tinjau batas penggunaan aplikasi Chat Anda dan jumlah data yang dijadwalkan untuk diimpor dari platform pesan sumber guna menentukan perkiraan linimasa.

Saat mengimpor pesan ke ruang, sebaiknya sebarkan panggilan ke metode messages.create() di berbagai rangkaian pesan.

Mengidentifikasi ruang yang didukung untuk diimpor

Mode impor hanya mendukung SpaceType dari SPACE dan GROUP_CHAT. Fitur ini tidak mendukung DIRECT_MESSAGE. Lihat dokumentasi untuk SpaceType untuk mengetahui informasi selengkapnya.

Membuat ruang dalam mode impor

Untuk membuat ruang dalam mode impor, panggil metode create pada resource Space dan tetapkan importMode ke true.

Saat Anda membuat ruang dalam mode impor, perhatikan hal berikut.

• Tanggal dan waktu - Ingat, mode impor harus diselesaikan dalam waktu 90 hari. Jika ruang masih dalam mode impor setelah 90 hari sejak metode spaces.create() dipanggil, ruang tersebut akan otomatis dihapus dan tidak dapat diakses serta tidak dapat dipulihkan.
  • Gunakan nilai kolom importModeExpireTime untuk melacak masa berlaku jangka waktu 90 hari.
  • Jangan gunakan nilai kolom createTime untuk melacak masa berlaku jangka waktu 90 hari. Hal ini tidak selalu sama dengan saat Anda memanggil metode spaces.create(). Saat menggunakan mode impor, kolom createTime dapat disetel ke stempel waktu historis saat ruang dibuat di sumber untuk mempertahankan waktu pembuatan asli.
• Nama resource ruang (name) - ID unik yang digunakan untuk mengambil informasi tentang ruang tertentu dan dirujuk pada langkah-langkah selanjutnya saat mengimpor konten ke dalam ruang.

Untuk mempertahankan waktu pembuatan entity ruang yang setara dari platform pesan sumber, Anda dapat menetapkan createTime ruang. createTime ini harus ditetapkan ke nilai antara 1 Januari 2000 dan saat ini.

Untuk membuat ruang eksternal dalam mode impor, tetapkan externalUserAllowed ke true. Setelah impor berhasil diselesaikan, Anda dapat menambahkan pengguna eksternal.

Contoh berikut menunjukkan cara membuat ruang dalam mode impor:

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)

Ganti kode berikut:

• EMAIL: alamat email akun pengguna yang Anda tiru dengan otoritas di seluruh domain.
• DISPLAY_NAME: nama ruang yang dibuat dalam mode impor. Nama ini harus unik untuk ruang yang ditampilkan kepada pengguna Chat. Sebaiknya gunakan nama tampilan yang sama dengan ruang tempat Anda mengimpor data.

Mengimpor resource

Untuk mengimpor resource dari platform pesan lain, Anda membuat resource Google Chat (seperti pesan, reaksi, lampiran) di ruang mode impor. Saat membuat resource di ruang, Anda menentukan data dari resource terkait dari platform pesan yang Anda migrasikan.

Pesan

Aplikasi Chat Anda dapat mengimpor pesan menggunakan otoritasnya sendiri, atau atas nama pengguna melalui peniruan identitas. Penulis pesan disetel ke akun pengguna yang ditiru identitasnya. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat. Untuk mengimpor pesan di ruang mode impor, panggil metode create pada resource Message. Untuk mempertahankan waktu pembuatan pesan asli dari platform pesan sumber, Anda dapat menetapkan createTime pesan. createTime ini harus disetel ke nilai antara waktu pembuatan ruang yang Anda tetapkan sebelumnya dan waktu saat ini.

Pesan di ruang yang sama tidak boleh berisi createTime yang sama, meskipun pesan sebelumnya dengan waktu tersebut dihapus.

Pesan yang berisi URL pihak ketiga di ruang mode impor tidak dapat merender pratinjau link dalam Google Chat.

Saat Anda membuat pesan dalam mode impor, ruang tidak akan mengirimkan notifikasi atau email kepada pengguna mana pun, termasuk pesan yang berisi sebutan pengguna.

Contoh berikut menunjukkan cara membuat pesan di ruang mode impor:

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

Ganti kode berikut:

• EMAIL: alamat email akun pengguna yang Anda lakukan peniruan identitasnya dengan otoritas di seluruh domain.
• SPACE_NAME: nama ruang yang dibuat dalam mode impor.

Reaksi

Aplikasi Chat Anda dapat mengimpor reaksi untuk pesan dengan menggunakan Chat API. Untuk mengetahui informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Mengizinkan aplikasi Chat.

Lampiran

Aplikasi Chat Anda dapat mengupload lampiran menggunakan Chat API. Untuk mengetahui informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Mengizinkan aplikasi Chat. Namun, sebaiknya Anda menggunakan Google Drive API untuk mengupload lampiran sebagai file Google Drive dan menautkan URI file ke pesan masing-masing di ruang mode impor untuk mengimpor lampiran dari platform pesan lain agar tidak mencapai batas internal Google Chat untuk upload lampiran.

Keanggotaan historis

Keanggotaan historis adalah keanggotaan yang dibuat untuk pengguna yang telah keluar dari entitas ruang asli dari platform pesan sumber, tetapi Anda ingin mempertahankan data mereka di Chat. Untuk mengetahui informasi tentang cara menambahkan anggota baru setelah ruang tidak lagi dalam mode impor, lihat Membuat resource keanggotaan.

Dalam banyak kasus, saat anggota historis tersebut tunduk pada kebijakan retensi data di Google, Anda ingin mempertahankan data (seperti Pesan dan reaksi) yang dibuat oleh keanggotaan historis di ruang sebelum mengimpornya ke Chat. Saat ruang dalam mode impor, Anda dapat mengimpor keanggotaan historis tersebut ke dalam ruang, menggunakan metode create di resource Membership. Untuk mempertahankan waktu keluar dari keanggotaan historis, Anda harus menetapkan deleteTime keanggotaan. Waktu keluar ini harus akurat karena memengaruhi data yang akan dipertahankan untuk keanggotaan tersebut. Selain itu, deleteTime harus setelah stempel waktu pembuatan ruang dan tidak boleh berupa stempel waktu mendatang.

Selain deleteTime, Anda juga dapat menyetel createTime untuk mempertahankan waktu bergabung asli langganan historis. Tidak seperti deleteTime, createTime bersifat opsional. Jika tidak disetel, createTime akan dihitung secara otomatis dengan mengurangi 1 mikrodetik dari deleteTime. Jika ditetapkan, createTime harus sebelum deleteTime dan harus pada atau setelah waktu pembuatan ruang. createTime Informasi ini tidak digunakan untuk menentukan retensi data dan tidak terlihat di alat admin seperti konsol Google Admin dan Google Vault.

Meskipun ada beberapa cara pengguna dapat bergabung dan keluar dari ruang di platform pesan sumber (melalui undangan, bergabung sendiri, ditambahkan oleh pengguna lain), di Chat, semua tindakan tersebut diwakili oleh kolom keanggotaan historis createTime dan deleteTime sebagai ditambahkan atau dihapus.

Contoh berikut menunjukkan cara membuat keanggotaan historis di ruang mode impor:

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

Ganti kode berikut:

• EMAIL: alamat email akun pengguna yang Anda lakukan peniruan identitasnya dengan otoritas di seluruh domain.
• SPACE_NAME: nama ruang yang dibuat dalam mode impor.
• USER_ID: ID unik untuk pengguna.

Mengimpor resource di ruang eksternal

Anda hanya dapat membuat ruang eksternal dengan mode impor menggunakan kredensial milik pengguna di dalam organisasi Workspace Anda. Hal ini hanya berlaku saat ruang berada dalam mode impor. Setelah ruang menyelesaikan mode impor, pengguna eksternal dapat diundang untuk bergabung ke ruang yang diimpor (lihat bagian akses) dan kredensial mereka dapat digunakan untuk memanggil Chat API.

Memvalidasi resource yang diimpor

Aplikasi Chat Anda dapat membaca kembali dan memvalidasi konten ruang mode impor dengan memanggil metode list di Message resource. Anda dapat membaca resource Reaction dan Attachment dari kolom emojiReactionSummaries dan attachment pesan yang ditampilkan. Aplikasi chat hanya dapat memanggil metode ini atas nama pengguna melalui peniruan identitas. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Aplikasi Chat Anda juga dapat membaca setiap pesan untuk validasi dengan memanggil metode get pada resource Message. Aplikasi chat hanya dapat memanggil metode ini untuk membaca pesannya sendiri dengan menggunakan otoritasnya sendiri. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Aplikasi chat juga dapat mencantumkan keanggotaan historis dengan memanggil metode list pada resource Membership. Setelah ruang keluar dari mode impor, metode list tidak lagi mengekspos keanggotaan historis. Aplikasi chat hanya dapat memanggil metode ini atas nama pengguna melalui peniruan identitas. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Anda dapat membaca properti ruang mode impor dengan memanggil metode get pada resource Space. Respons juga akan diisi importModeExpireTime, sehingga Anda dapat melacak jangka waktu untuk menyelesaikan proses impor dengan benar. Aplikasi chat hanya dapat memanggil metode ini menggunakan otoritasnya sendiri. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Menyesuaikan perbedaan resource yang diimpor dari data sumber

Jika ada resource yang diimpor tidak lagi cocok dengan entitas asli dari platform pesan sumber karena perubahan pada entitas asli selama impor, aplikasi Chat dapat memanggil Chat API untuk mengubah resource chat yang diimpor. Misalnya, jika pengguna mengedit pesan di platform pesan sumber setelah pesan tersebut dibuat di Chat, aplikasi Chat dapat memperbarui pesan yang diimpor sehingga mencerminkan konten pesan asli saat ini.

Pesan

Untuk memperbarui kolom yang didukung pada pesan di ruang mode impor, panggil metode update pada resource Message. Aplikasi chat hanya dapat memanggil metode ini menggunakan otoritas yang sama yang digunakan selama pembuatan pesan awal. Jika Anda menggunakan peniruan identitas pengguna selama pembuatan pesan awal, Anda harus menggunakan pengguna yang sama yang identitasnya ditiru untuk memperbarui pesan tersebut.

Untuk menghapus pesan di ruang mode impor, panggil metode delete pada resource Message. Pesan dalam ruang mode impor tidak perlu dihapus oleh pembuat pesan asli dan dapat dihapus dengan meniru identitas pengguna mana pun dalam domain. Aplikasi Chat hanya dapat menghapus pesannya sendiri menggunakan otoritasnya sendiri. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Reaksi

Untuk menghapus reaksi pada pesan di ruang mode impor, gunakan metode delete pada resource reactions. Untuk mengetahui informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Mengizinkan aplikasi Chat.

Lampiran

Untuk memperbarui lampiran pesan di ruang mode impor, gunakan metode upload pada resource media. Untuk mengetahui informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Mengizinkan aplikasi Chat.

Keanggotaan historis

Untuk menghapus keanggotaan historis di ruang mode impor, gunakan metode delete pada resource Membership. Setelah ruang keluar dari mode impor, metode delete tidak lagi memungkinkan Anda menghapus keanggotaan historis.

Anda tidak dapat memperbarui keanggotaan historis di ruang mode impor. Jika Anda ingin mengoreksi keanggotaan historis yang diimpor secara keliru, Anda harus menghapusnya terlebih dahulu, lalu membuatnya ulang saat ruang masih dalam mode impor.

Ruang

Untuk memperbarui kolom yang didukung di ruang mode impor, gunakan metode patch pada resource spaces.

Untuk menghapus ruang mode impor, gunakan metode delete pada resource spaces.

Untuk mengetahui informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Memberi otorisasi aplikasi Chat.

Mode impor lengkap

Sebelum memanggil metode completeImport, Anda harus memastikan bahwa validasi dan rekonsiliasi perbedaan resource telah selesai. Keluar dari ruang mode impor adalah proses yang tidak dapat diurungkan dan mengubah ruang mode impor menjadi ruang biasa. Tidak ada indikator di Chat yang mengatribusikan ruang ini ke impor data.

Catat tanggal dan waktu Anda memanggil completeImport, nama resource pengguna yang melakukan panggilan, dan respons yang ditampilkan. Hal ini dapat membantu jika Anda mengalami masalah dan harus menyelidikinya.

Untuk menyelesaikan mode impor dan membuat ruang dapat diakses oleh pengguna, aplikasi Chat dapat memanggil metode completeImport di resource Space. Aplikasi chat hanya dapat memanggil metode ini atas nama pengguna melalui peniruan identitas. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat. Pengguna yang di-impersonate ditambahkan ke ruang sebagai pengelola ruang setelah metode ini selesai. Metode ini harus dipanggil dalam waktu 90 hari sejak panggilan metode create.space awal. Jika Anda mencoba memanggil metode ini setelah durasi 90 hari berlalu, panggilan akan gagal karena ruang mode impor dihapus dan tidak lagi dapat diakses oleh aplikasi Chat.

Pengguna yang di-impersonate dalam metode completeImport tidak harus menjadi pembuat ruang.

Jangan memanggil completeImport terlalu dekat dengan importModeExpireTime, karena kami tidak dapat menjamin bahwa permintaan akan tiba sebelum importModeExpireTime, dan dapat terjadi konflik dengan pemrosesan data dalam sistem yang dipicu pada waktu habis masa berlaku. Sebaiknya hubungi completeImport setidaknya 30 menit sebelum importModeExpireTime.

Contoh berikut menunjukkan cara menyelesaikan mode impor:

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

Ganti kode berikut:

• EMAIL: alamat email akun pengguna yang Anda lakukan peniruan identitasnya dengan otoritas di seluruh domain.
• SPACE_NAME: nama ruang yang dibuat dalam mode impor.

Memberi akses ke ruang setelah mode impor

Untuk memberi pengguna Chat akses ke ruang yang baru diimpor, aplikasi Chat dapat terus menggunakan cakupan chat.import dan peniruan identitas pengguna dalam waktu 90 hari setelah panggilan metode create.space() awal untuk melakukan hal berikut:

• Menambahkan anggota ke ruang: Panggil metode create() pada resource Membership. Sebaiknya aplikasi Chat membuat resource Membership segera setelah impor ruang selesai, sehingga aplikasi Chat dapat terus menggunakan cakupan chat.import, dan memastikan bahwa semua anggota yang diimpor memiliki akses ke ruang. Anda harus memprioritaskan penambahan anggota yang mungkin tunduk pada kebijakan pembekuan Vault, yang memungkinkan penyimpanan pesan yang diimpor meskipun pesan tersebut melebihi periode retensi.
• Tetapkan audiens target: Panggil metode update() pada resource Space. Untuk mempelajari cara membuat dan menambahkan target audiens, lihat Membuat ruang Google Chat dapat ditemukan oleh pengguna tertentu di organisasi Google Workspace.

Untuk menggunakan metode ini dengan cakupan chat.import, pengguna yang di-impersonate harus menjadi pengelola ruang.

Untuk ruang eksternal, metode create() keanggotaan juga memungkinkan pengguna diundang dari luar organisasi Workspace Anda. Pastikan Anda memahami semua batasan yang diketahui untuk pengguna eksternal.

Pemecahan masalah

Jika Anda mengalami masalah saat mengimpor ruang Chat, tinjau masalah berikut untuk mendapatkan bantuan. Jika Anda mengalami respons error, catat (salin/tempel teks ke dalam dokumen atau simpan screenshot) untuk referensi dan pemecahan masalah di masa mendatang.

Jika ruang berhasil diimpor, CompleteImportSpace akan selesai dengan status OK.

Tidak menyelesaikan impor sebelum periode 90 hari berakhir

Seperti yang dijelaskan sebelumnya di Membuat ruang dalam mode impor, jika ruang masih dalam mode impor setelah 90 hari sejak metode pembuatan dipanggil, ruang tersebut akan otomatis dihapus dan menjadi tidak dapat diakses serta tidak dapat dipulihkan.

Sayangnya, ruang yang dihapus tidak lagi tersedia atau dapat dipulihkan dan proses impor harus dimulai lagi.

Jika ruang tidak diimpor karena memiliki terlalu banyak data untuk diimpor dalam jangka waktu 90 hari dengan batas penggunaan saat ini, pisahkan ruang menjadi dua atau lebih ruang yang lebih kecil untuk tujuan pengarsipan, lalu mulai proses impor lagi.

Menemukan ruang yang hilang

Jika Anda tidak dapat menemukan ruang Chat baru, tinjau tabel berikut untuk melihat respons yang Anda terima dari CompleteImportSpace, penjelasan, dan cara menyelesaikannya.