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 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 dalam 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. Menyelesaikan mode impor
8. Memberikan akses ke ruang setelah mode impor
9. Pemecahan masalah

Prasyarat

Rencanakan impor Anda

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.

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 untuk menentukan estimasi 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. Metode ini 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 30 hari. Jika ruang masih dalam mode impor setelah 30 hari sejak metode spaces.create() dipanggil, ruang tersebut akan otomatis dihapus serta tidak dapat diakses dan tidak dapat dipulihkan.
  • Jangan gunakan nilai kolom createTime untuk melacak habis masa berlaku jangka waktu 30 hari. Hal ini tidak selalu sama seperti 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 di langkah-langkah berikutnya 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 tirukan dengan otorisasi seluruh domain.
• DISPLAY_NAME: nama untuk ruang yang dibuat dalam mode impor. Nama ini harus unik untuk ruang yang ditampilkan ke pengguna Chat. Sebaiknya gunakan nama tampilan yang sama dengan ruang tempat Anda mengimpor data.

Mengimpor resource

Untuk mengimpor resource dari platform pesan lain, buat 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 Mengizinkan 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 menyetel 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 dapat 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 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 secara mandiri, ditambahkan oleh pengguna lain), di Chat, semua tindakan tersebut direpresentasikan oleh kolom createTime dan deleteTime historis keanggotaan sebagai telah 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 di 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 mengetahui informasi selengkapnya, lihat Mengizinkan 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 otorisasinya sendiri. Untuk mengetahui informasi selengkapnya, lihat Memberi otorisasi 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 Memberi otorisasi aplikasi Chat.

Anda dapat membaca properti ruang mode impor dengan memanggil metode get pada resource Space. Aplikasi chat hanya dapat memanggil metode ini menggunakan otorisasi mereka sendiri. Untuk mengetahui informasi selengkapnya, lihat Mengizinkan aplikasi Chat.

Merekonsiliasi perbedaan resource yang diimpor dari data sumber

Jika resource yang diimpor tidak lagi cocok dengan entity asli dari platform pesan sumber karena adanya perubahan pada entity asli selama proses 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 pada 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 pada 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 informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Mengizinkan aplikasi Chat.

Lampiran

Untuk memperbarui lampiran pesan dalam 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 mengizinkan Anda menghapus langganan historis.

Anda tidak dapat memperbarui langganan historis di ruang mode impor. Jika ingin memperbaiki keanggotaan historis yang diimpor dengan tidak benar, 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 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 30 hari sejak panggilan metode create.space awal. Jika Anda mencoba memanggil metode ini setelah durasi 30 hari berlalu, panggilan akan mengalami kegagalan karena ruang mode impor dihapus dan tidak dapat diakses lagi oleh aplikasi Chat.

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

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 tiru identitasnya dengan otoritas 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-baru ini diimpor, aplikasi Chat dapat terus menggunakan cakupan chat.import dan peniruan identitas pengguna dalam waktu 30 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.
• Menetapkan target audiens: Panggil metode update() di 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 Anda mengundang pengguna di luar organisasi Workspace Anda. Pastikan Anda memahami semua batasan umum 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.

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

Tidak menyelesaikan impor sebelum periode 30 hari berakhir

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

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

Menemukan ruang yang hilang

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