Mengimpor data ke Google Chat

Dengan Google Chat API, Anda dapat mengimpor data dari platform pesan lain ke Google Chat. Anda dapat mengimpor pesan, lampiran, reaksi, keanggotaan, dan entity 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 materi
5. Memvalidasi resource yang diimpor
6. Menyatukan perbedaan resource yang diimpor dari data sumber
7. Mode impor lengkap
8. Memberikan akses ke ruang setelah mode impor
9. Pemecahan masalah

Prasyarat

Merencanakan impor

Rencanakan jumlah data yang akan diimpor dengan tepat, pahami bagaimana batas penggunaan dan kuota dapat memengaruhi proses impor, dan ketahui jenis ruang Chat yang didukung saat mengimpor ke ruang baru. Jika Anda adalah administrator, baca 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 dan jumlah data yang dijadwalkan untuk diimpor dari platform pesan sumber untuk menentukan perkiraan linimasa.

Saat mengimpor pesan ke ruang, sebaiknya Anda menyebarkan 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. PostgreSQL tidak mendukung DIRECT_MESSAGE. Lihat dokumentasi untuk SpaceType untuk informasi selengkapnya.

Membuat ruang dalam mode impor

Untuk membuat ruang dalam mode impor, panggil metode create di 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 habis masa berlaku jangka waktu 90 hari.
  • Jangan gunakan nilai kolom createTime untuk melacak habis 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 ditetapkan 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 berikutnya saat mengimpor konten ke 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 tirukan dengan otorisasi seluruh domain.
• DISPLAY_NAME: nama untuk 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 tempat Anda bermigrasi.

Pesan

Aplikasi Chat Anda dapat mengimpor pesan menggunakan otorisasinya sendiri, atau atas nama pengguna melalui peniruan identitas. Penulis pesan ditetapkan ke akun pengguna yang disamarkan. Untuk mengetahui informasi selengkapnya, lihat Memberi otorisasi aplikasi Chat. Untuk mengimpor pesan di ruang mode impor, panggil metode create di resource Message. Untuk mempertahankan waktu pembuatan pesan asli dari platform pesan sumber, Anda dapat menetapkan createTime pesan. createTime ini harus ditetapkan ke nilai antara waktu pembuatan ruang yang sebelumnya Anda tetapkan 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 memberi tahu atau mengirim 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 impersonasikan dengan otorisasi seluruh domain.
• SPACE_NAME: nama untuk ruang yang dibuat dalam mode impor.

Reaksi

Aplikasi Chat Anda dapat mengimpor reaksi untuk pesan 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 gunakan 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

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

Dalam banyak kasus, jika 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 langganan historis tersebut ke ruang, menggunakan metode create di resource Membership. Untuk mempertahankan waktu keluar dari langganan historis, Anda harus menetapkan deleteTime langganan. Waktu berhenti berlangganan ini harus akurat karena memengaruhi data yang akan dipertahankan untuk langganan tersebut. Selain itu, deleteTime ini harus setelah stempel waktu pembuatan ruang dan tidak boleh berupa stempel waktu mendatang.

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

Meskipun mungkin ada beberapa cara bagi pengguna untuk 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 createTime dan deleteTime keanggotaan historis 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 impersonasikan dengan otorisasi seluruh domain.
• SPACE_NAME: nama untuk 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 yang dimiliki pengguna di dalam organisasi Workspace Anda. Hal ini hanya berlaku saat ruang 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 pada resource Message. 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 informasi selengkapnya, lihat Memberi otorisasi aplikasi Chat.

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

Aplikasi chat juga dapat mencantumkan keanggotaan historis dengan memanggil metode list di 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 Memberi otorisasi aplikasi Chat.

Anda dapat membaca properti ruang mode impor dengan memanggil metode get di resource Space. Respons juga akan mengisi importModeExpireTime, sehingga Anda dapat melacak rentang waktu dengan benar untuk menyelesaikan proses impor. Aplikasi chat hanya dapat memanggil metode ini menggunakan otorisasi mereka sendiri. Untuk mengetahui informasi selengkapnya, lihat Memberi otorisasi aplikasi Chat.

Menyelaraskan perbedaan resource yang diimpor dari data sumber

Jika 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 asal 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 di resource Message. Aplikasi chat hanya dapat memanggil metode ini menggunakan otorisasi yang sama dengan yang digunakan selama pembuatan pesan awal. Jika Anda menggunakan peniruan identitas pengguna selama pembuatan pesan awal, Anda harus menggunakan pengguna yang diimpersonasikan yang sama untuk memperbarui pesan tersebut.

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

Reaksi

Untuk menghapus reaksi 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 langganan historis di ruang mode impor, gunakan metode delete di resource Membership. Setelah ruang keluar dari mode impor, metode delete tidak lagi mengizinkan Anda menghapus langganan historis.

Anda tidak dapat memperbarui langganan historis di ruang mode impor. Jika ingin memperbaiki langganan historis yang salah diimpor, 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, dan 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 mengonversi ruang mode impor menjadi ruang reguler. 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 Memberi otorisasi aplikasi Chat. Pengguna yang disamarkan akan 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 mengalami kegagalan karena ruang mode impor dihapus dan tidak dapat lagi diakses oleh aplikasi Chat.

Pengguna yang disamarkan dalam metode completeImport tidak harus menjadi pembuat ruang.

Jangan panggil completeImport terlalu dekat dengan importModeExpireTime, karena kami tidak dapat memastikan bahwa permintaan akan tiba sebelum importModeExpireTime, dan mungkin ada konflik dengan pemrosesan data dalam sistem yang dipicu pada waktu habis masa berlaku. Sebaiknya panggil 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 impersonasikan dengan otorisasi seluruh domain.
• SPACE_NAME: nama untuk ruang yang dibuat dalam mode impor.

Memberikan 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 sejak 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 sudah tidak lagi dipertahankan.
• Menetapkan 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 merupakan pengelola ruang.

Untuk ruang eksternal, metode create() keanggotaan juga memungkinkan Anda mengundang pengguna di 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 respons tersebut (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 tidak dapat diakses serta tidak dapat dipulihkan.

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

Menemukan ruang yang hilang

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