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:
- Merencanakan impor
- Mengonfigurasi otorisasi untuk aplikasi Chat
- Membuat ruang dalam mode impor
- Mengimpor materi
- Memvalidasi resource yang diimpor
- Menyatukan perbedaan resource yang diimpor dari data sumber
- Mode impor lengkap
- Memberikan akses ke ruang setelah mode impor
- Pemecahan masalah
Prasyarat
Apps Script
- Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
- Buat project Google Cloud.
- Aktifkan dan konfigurasikan Google Chat API dengan nama, ikon, dan deskripsi untuk aplikasi Chat Anda.
- Buat project Apps Script mandiri, dan aktifkan Layanan Chat Lanjutan.
- Aplikasi Chat harus didelegasikan otorisasi di seluruh domain di domain tempat aplikasi mengimpor konten, lihat Memberi otorisasi aplikasi Chat.
Python
- Akun Google Workspace Business atau Enterprise dengan akses ke Google Chat.
- Buat project Google Cloud.
- Aktifkan dan konfigurasikan Google Chat API dengan nama, ikon, dan deskripsi untuk aplikasi Chat Anda.
- Python 3.6 atau yang lebih tinggi
- Alat pengelolaan paket pip
- Aplikasi Chat harus didelegasikan otorisasi di seluruh domain di domain tempat aplikasi mengimpor konten, lihat Memberi otorisasi aplikasi Chat.
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 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 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 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 seperti saat Anda memanggil metodespaces.create()
. Saat menggunakan mode impor, kolomcreateTime
dapat ditetapkan ke stempel waktu historis saat ruang dibuat di sumber untuk mempertahankan waktu pembuatan asli.
- Gunakan nilai kolom
- 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:
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 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:
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:
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 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
mengurangkan 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:
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:
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 otorisasinya 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 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 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 di-impersonate 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
terjadi 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:
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:
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 resourceMembership
. Sebaiknya aplikasi Chat membuat resourceMembership
segera setelah impor ruang selesai, sehingga aplikasi Chat dapat terus menggunakan cakupanchat.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 resourceSpace
. 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 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.
Saat 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.
Respons diterima | Langkah-langkah investigasi | Penjelasan | Resolusi |
---|---|---|---|
CompleteImportSpace menampilkan pengecualian dan memanggil
GetSpace akan menampilkan PERMISSION_DENIED . |
Periksa catatan Anda untuk mengetahui kapan ruang dibuat dan jika sudah lebih dari 90 hari, ruang tersebut akan otomatis dihapus. Selain itu, tidak ada data ruang yang diimpor di alat pengelolaan ruang atau log audit. | Sudah lebih dari 90 hari sejak proses impor dimulai dan ruang gagal keluar dari migrasi. | Buat ruang baru dan jalankan kembali proses impor. |
CompleteImportSpace menampilkan OK dan memanggil
GetSpace akan menampilkan PERMISSION_DENIED . |
Tidak ada catatan ruang yang diimpor di alat pengelolaan ruang, tetapi ruang tersebut ditampilkan telah dihapus di log audit. | Ruang berhasil diimpor, tetapi kemudian dihapus. | Buat ruang baru dan jalankan kembali proses impor. |