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 angkasa dari platform pesan Anda yang lain untuk sesuai Referensi Chat API. Anda dapat mengimpor data ini dengan membuat ruang Chat di mode impor dan mengimpor data ke dalam ruang tersebut. Setelah proses berhasil diselesaikan, ruang ini menjadi ruang Chat standar.

Berikut adalah proses impor selengkapnya:

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

Prasyarat

Apps Script

Python

  • Python 3.6 atau yang lebih baru
  • pip alat pengelolaan paket

  • Library klien Google terbaru untuk Python. Untuk menginstal atau mengupdate jalankan perintah berikut di antarmuka command line Anda:

    pip3 install --upgrade google-api-python-client google-auth

  • Aplikasi Chat yang dipublikasikan. Untuk membuat dan memublikasikan aplikasi Chat, lihat Buat aplikasi Google Chat.

  • Otorisasi yang dikonfigurasi untuk aplikasi Chat. Tujuan Aplikasi Chat harus didelegasikan ke otoritas seluruh domain di domain tempat aplikasi mengimpor konten, lihat Izinkan aplikasi Chat.

Merencanakan impor

Merencanakan jumlah data yang akan diimpor, memahami bagaimana batas dan kuota penggunaan dapat memengaruhi proses impor, dan memperhatikan jenis ruang Chat didukung saat mengimpor ke ruang baru.

Meninjau batas penggunaan API

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

Saat mengimpor pesan ke ruang, sebaiknya Anda menyebarkan panggilan ke messages.create() di berbagai thread pesan.

Mengidentifikasi ruang yang didukung untuk diimpor

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

Membuat ruang dalam mode impor

Untuk membuat ruang dalam mode impor, panggil metode Metode create di Resource Space dan setel importMode ke true.

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

  • Tanggal dan waktu - Ingat, mode impor harus diselesaikan dalam waktu 30 hari. Jika ruang masih dalam mode impor setelah 30 detik hari sejak metode spaces.create() dipanggil, otomatis terhapus dan menjadi tidak dapat diakses dan tidak dapat dipulihkan.
    • Jangan gunakan nilai createTime untuk melacak berakhirnya jangka waktu 30 hari. Ini bukan selalu sama seperti saat Anda memanggil metode spaces.create(). Kapan menggunakan mode impor, kolom createTime dapat ditetapkan ke histori stempel waktu saat ruang dibuat di sumber untuk mempertahankan waktu pembuatan asli.
  • Nama resource ruang (name) - Pengenal unik yang digunakan untuk mengambil informasi tentang ruang tertentu dan dirujuk pada langkah selanjutnya saat mengimpor konten ke luar angkasa.

Untuk mempertahankan waktu pembuatan entitas ruang yang setara dari sumber platform pesan, Anda dapat menyetel createTime ruang. Ini createTime harus ditetapkan ke nilai antara 1 Januari 2000 dan waktu 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:

Apps Script

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);
}

Python

"""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 meniru identitas Anda dengan otoritas seluruh domain.
  • DISPLAY_NAME: nama untuk ruang yang dibuat di mode impor. Nama ini harus unik untuk ruang yang ditampilkan Pengguna Chat. Sebaiknya gunakan nama tampilan yang sama dengan ruang tempat Anda mengimpor data.

Mengimpor resource

Untuk mengimpor referensi dari platform pesan lain, buat Google Chat (seperti pesan, reaksi, lampiran) di ruang mode impor. Saat membuat resource dalam ruang, Anda menentukan data dari resource terkait resource dari platform pesan tempat asal migrasi.

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 informasi selengkapnya, lihat Izinkan aplikasi Chat. Untuk mengimpor dalam ruang mode impor, panggil metode Metode create di Resource Message. Untuk mempertahankan waktu pembuatan pesan asli dari sumber platform pesan, Anda dapat menyetel createTime pesan. Ini createTime harus ditetapkan ke nilai antara waktu pembuatan ruang yang Anda yang telah ditetapkan sebelumnya dan waktu saat ini.

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

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

Saat Anda membuat pesan dalam mode impor, ruang tidak akan memberi tahu atau mengirim email kepada setiap pengguna, termasuk pesan yang berisi sebutan pengguna.

Contoh berikut menunjukkan cara membuat pesan di ruang mode impor:

Python

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

Reaksi

Aplikasi Chat Anda dapat mengimpor reaksi untuk pesan menggunakan Chat API. Untuk informasi tentang metode resource dan jenis dukungan autentikasi di ruang mode impor, lihat Izinkan 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 Izinkan 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 agar tidak mencapai batas internal Google Chat untuk lampiran upload.

Histori keanggotaan

Keanggotaan historis adalah keanggotaan yang dibuat untuk pengguna yang telah keluar dari program. 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 diimpor Anda, lihat Membuat fasilitas langganan.

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

Selain deleteTime, Anda juga dapat menetapkan createTime untuk mempertahankan waktu bergabung awal dari keanggotaan historis. Tidak seperti deleteTime, createTime bersifat opsional. Jika tidak disetel, createTime akan otomatis dihitung oleh deleteTime dikurangi 1 mikrodetik. Jika ditetapkan, createTime harus sebelum deleteTime dan harus berada pada atau setelah waktu pembuatan ruang. createTime ini informasi tidak digunakan untuk menentukan retensi data dan tidak terlihat di admin alat 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 langganan createTime dan deleteTime historis ditambahkan atau dihapus.

Contoh berikut menunjukkan cara membuat keanggotaan historis dalam proses impor ruang mode:

Python

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

Mengimpor resource di ruang eksternal

Anda hanya dapat membuat ruang eksternal dengan mode impor menggunakan kredensial milik pengguna di dalam organisasi Workspace Anda. Hanya berlaku saat ruang berada dalam mode impor. Setelah spasi menyelesaikan mode impor, pengguna eksternal dapat diundang untuk bergabung ke ruang yang diimpor (lihat bagian akses) dan kredensialnya 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 pesan yang ditampilkan mana pun Kolom emojiReactionSummaries dan attachment. Aplikasi chat dapat hanya memanggil metode ini atas nama pengguna melalui peniruan identitas. Untuk selengkapnya informasi, lihat Izinkan aplikasi Chat.

Aplikasi Chat Anda juga dapat membaca pesan individual untuk validasi dengan memanggil Metode get pada resource Message. Aplikasi Chat hanya dapat memanggil metode ini untuk membaca pesannya sendiri dengan menggunakan otoritas mereka sendiri. Untuk informasi selengkapnya, lihat Izinkan 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 akan menampilkan histori keanggotaan lagi. Aplikasi Chat hanya dapat memanggil metode ini di nama pengguna melalui peniruan identitas. Untuk informasi selengkapnya, lihat Izinkan aplikasi Chat.

Anda dapat membaca properti ruang mode impor dengan memanggil metode Metode get di Resource Space. Aplikasi Chat hanya dapat memanggil metode ini menggunakan otoritasnya sendiri. Untuk informasi selengkapnya, lihat Izinkan aplikasi Chat.

Merekonsiliasi perbedaan resource yang diimpor dari data sumber

Jika resource yang diimpor tidak lagi cocok dengan entitas asli dari sumbernya karena perubahan entitas asli selama proses impor, Aplikasi chat dapat memanggil Chat API untuk mengubah teks yang diimpor referensi chat. Misalnya, jika pengguna mengedit pesan di pesan sumber platform baru setelah pesan itu dibuat di Chat, Aplikasi Chat dapat mengupdate pesan yang diimpor sehingga mencerminkan isi pesan asli saat ini.

Pesan

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

Untuk menghapus pesan dalam ruang mode impor, panggil metode Metode delete di Resource Message. Pesan di ruang mode impor tidak perlu dihapus oleh versi aslinya pembuat pesan dan dapat dihapus dengan melakukan peniruan identitas pengguna mana pun di domain tersebut. Aplikasi Chat hanya dapat menghapus pesan mereka sendiri menggunakan pesannya sendiri {i>authority<i}. Untuk informasi selengkapnya, lihat Izinkan aplikasi Chat.

Reaksi

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

Lampiran

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

Histori keanggotaan

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

Anda tidak dapat memperbarui keanggotaan historis di ruang mode impor. Jika Anda ingin memperbaiki keanggotaan historis yang diimpor dengan tidak benar, Anda harus menghapusnya terlebih dahulu, lalu membuatnya kembali 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 Izinkan aplikasi Chat.

Selesaikan mode impor

Sebelum memanggil completeImport Anda harus memastikan bahwa validasi dan rekonsiliasi perbedaan resource diselesaikan. Keluar dari ruang dari mode impor adalah proses yang tidak dapat dibatalkan 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 dihasilkan. Hal ini dapat bermanfaat 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 referensi Space. Aplikasi Chat hanya dapat memanggil metode ini atas nama pengguna melalui peniruan identitas. Untuk informasi selengkapnya, lihat Izinkan aplikasi Chat. Pengguna yang ditiru identitasnya 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 telah berlalu, panggilan mengakibatkan kegagalan karena impor ruang mode dihapus dan tidak lagi dapat diakses oleh Aplikasi Chat.

Pengguna yang ditiru identitasnya dalam metode completeImport tidak harus berupa pembuat ruang angkasa.

Contoh berikut menunjukkan cara menyelesaikan mode impor:

Python

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

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 pengguna peniruan identitas dalam waktu 30 hari sejak panggilan metode create.space() awal yang harus dilakukan hal berikut:

Untuk menggunakan metode ini dengan cakupan chat.import, pengguna yang ditiru identitasnya harus menjadi pengelola ruang.

Untuk ruang eksternal, langganan Metode create() 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 menemui respons {i>error<i}, pastikan catatannya (salin/tempel teks ke dokumen atau simpan {i>screenshot<i}) untuk referensi dan pemecahan masalah pada 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, data itu akan dihapus secara otomatis dan menjadi tidak dapat diakses dan tidak dapat dipulihkan.

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

Menemukan ruang yang tidak ada

Jika Anda tidak dapat menemukan ruang Chat baru, tinjau tabel berikut untuk respons yang Anda terima dari CompleteImportSpace terhadap lihat penjelasannya dan cara mengatasinya.

Respons diterima Langkah-langkah investigasi Penjelasan Resolusi
CompleteImportSpace menampilkan pengecualian dan memanggil GetSpace menampilkan PERMISSION_DENIED. Memeriksa data Anda untuk mengetahui waktu pembuatan ruang dan apakah ruang tersebut sudah lama dari 30 hari, data tersebut dihapus secara otomatis. Selain itu, tidak ada data ruang yang diimpor alat pengelolaan ruang atau log audit. Sudah lebih dari 30 hari sejak proses impor dimulai dan ruang gagal keluar dari migrasi. Buat ruang baru dan jalankan proses impor lagi.
CompleteImportSpace menampilkan OK dan memanggil GetSpace menampilkan PERMISSION_DENIED. Tidak ada catatan ruang yang diimpor dalam alat pengelolaan ruang, tetapi ruang itu ditampilkan sebagai telah dihapus di log audit. Ruang berhasil diimpor, tetapi kemudian dihapus. Buat ruang baru dan jalankan proses impor lagi.