Trang này được dịch bởi Cloud Translation API.

Nhập dữ liệu vào Google Chat

Với API Google Chat, bạn có thể nhập dữ liệu từ các nền tảng nhắn tin khác vào Google Chat. Bạn có thể nhập tin nhắn, tệp đính kèm, lượt thể hiện cảm xúc, gói thành viên và thực thể trong không gian hiện có từ các nền tảng nhắn tin khác vào tài nguyên API Chat tương ứng. Bạn có thể nhập dữ liệu này bằng cách tạo phòng Chat ở chế độ nhập và nhập dữ liệu vào các không gian đó. Sau khi quá trình hoàn tất thành công, các không gian này sẽ trở thành không gian Chat tiêu chuẩn.

Xem xét hạn mức sử dụng API và lập kế hoạch trước.
Định cấu hình việc uỷ quyền cho ứng dụng Chat.
Tạo không gian ở chế độ nhập.
Nhập tài nguyên.
Xác thực tài nguyên đã nhập.
Đối chiếu sự khác biệt về tài nguyên đã nhập với dữ liệu nguồn.
Hoàn tất chế độ nhập.
Tạo tài nguyên cho gói thành viên.

Điều kiện tiên quyết

Apps Script

Một tài khoản Google Workspace có quyền truy cập vào Google Chat.
Một ứng dụng Chat đã phát hành. Để tạo một ứng dụng Chat, hãy làm theo hướng dẫn quickstart sau đây.

Python

Python 3.6 trở lên
Công cụ quản lý gói pip
Các thư viện ứng dụng mới nhất của Google dành cho Python. Để cài đặt hoặc cập nhật các thành phần này, hãy chạy lệnh sau trong giao diện dòng lệnh:
```
pip3 install --upgrade google-api-python-client google-auth
```
Một ứng dụng Chat đã xuất bản. Để tạo và phát hành một ứng dụng Chat, hãy xem bài viết Tạo ứng dụng Google Chat.
Đã định cấu hình việc uỷ quyền cho ứng dụng Chat. Ứng dụng Chat phải được uỷ quyền trên toàn miền trong mọi miền mà ứng dụng nhập nội dung, hãy xem phần Uỷ quyền cho các ứng dụng trong Chat.

Xem xét các hạn mức sử dụng API và lên kế hoạch trước

Thời gian cần thiết để nhập dữ liệu vào Chat có thể khác nhau đáng kể tuỳ thuộc vào số lượng tài nguyên trong Chat cần nhập. Hãy lên kế hoạch trước bằng cách xem xét giới hạn sử dụng của ứng dụng Chat và lượng dữ liệu được lên lịch để nhập từ nền tảng nhắn tin nguồn để xác định tiến trình ước tính.

Tạo không gian ở chế độ nhập

Để tạo một không gian ở chế độ nhập, hãy gọi phương thức create trên tài nguyên Space và đặt importMode thành true. Để lưu giữ thời gian tạo của thực thể không gian tương đương từ nền tảng thông báo nguồn, bạn có thể đặt createTime của không gian. Bạn phải đặt createTime này thành một giá trị trong khoảng thời gian từ ngày 1 tháng 1 năm 2000 đến thời điểm hiện tại.

Ghi lại name của không gian bạn tạo để có thể tham chiếu đến các bước sau khi nhập nội dung vào không gian.

Kể từ thời điểm phương thức create được gọi, các ứng dụng trong Chat có 30 ngày để nhập tài nguyên vào không gian, để hoàn tất chế độ nhập và tạo tài nguyên thành viên bằng phạm vi chat.import. Các ứng dụng trong Chat vẫn có thể tạo gói thành viên sau 30 ngày với phạm vi thành viên tiêu chuẩn của API Chat. Sau 30 ngày, nếu không gian vẫn ở chế độ nhập, thì không gian đó sẽ tự động bị xoá và không thể truy cập được cũng như không thể khôi phục. Hãy lên kế hoạch trước bằng cách xem xét giới hạn sử dụng của ứng dụng Chat để đảm bảo có thể nhập tất cả tài nguyên theo lịch vào Chat trong khung thời gian này.

Ví dụ sau đây trình bày cách tạo một không gian ở chế độ nhập:

Apps Script

function createSpaceInImportMode() {
  const space = Chat.Spaces.create({
      spaceType: 'SPACE',
      displayName: 'Import Mode Space',
      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': 'Import Mode Space',
            'importMode': True,
            'createTime': f'{datetime.datetime(2000, 1, 1).isoformat()}Z',
        }
    )
    .execute()
)

print(result)

Thay thế đoạn mã sau:

EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh là một cơ quan có thẩm quyền trên toàn miền.

Nhập tài nguyên

Để nhập tài nguyên từ các nền tảng nhắn tin khác, bạn cần tạo tài nguyên Google Chat (chẳng hạn như tin nhắn, lượt thể hiện cảm xúc, tệp đính kèm) trong không gian chế độ nhập. Khi tạo tài nguyên trong không gian, bạn sẽ chỉ định dữ liệu của tài nguyên có liên quan từ nền tảng thông báo mà bạn đang di chuyển.

Tin nhắn

Các ứng dụng trong Chat có thể nhập tin nhắn bằng cách sử dụng thẩm quyền của riêng ứng dụng hoặc thay mặt cho người dùng bằng cách mạo danh. (Tác giả thông báo được đặt thành tài khoản người dùng mạo danh.) Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat. Để nhập thông báo vào không gian chế độ nhập, hãy gọi phương thức create trên tài nguyên Message. Để lưu giữ thời gian tạo tin nhắn gốc từ nền tảng nhắn tin nguồn, bạn có thể đặt createTime của thông báo. Bạn phải đặt createTime này thành một giá trị giữa thời gian tạo không gian mà bạn đã đặt trước đó và thời gian hiện tại.

Các tin nhắn trong cùng một không gian không được chứa cùng một createTime, ngay cả khi các tin nhắn trước đó có thời gian đó đã bị xoá.

Những tin nhắn chứa URL của bên thứ ba trong không gian ở chế độ nhập không thể hiển thị bản xem trước đường liên kết trong Google Chat.

Khi bạn tạo tin nhắn ở chế độ nhập, không gian sẽ không thông báo hoặc gửi email cho bất kỳ người dùng nào, kể cả tin nhắn chứa đề cập của người dùng.

Ví dụ sau đây cho biết cách tạo thông báo trong một không gian ở chế độ nhập:

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)

Thay thế đoạn mã sau:

EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh với thẩm quyền trên toàn miền.
SPACE_NAME: tên của không gian được tạo ở chế độ nhập.

Lượt thể hiện cảm xúc

Ứng dụng Chat có thể nhập phản ứng đối với tin nhắn bằng cách sử dụng API Chat. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép các ứng dụng trong Chat.

Phần đính kèm:

Ứng dụng Chat có thể tải tệp đính kèm lên bằng API Chat. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép các ứng dụng trong Chat. Tuy nhiên, bạn nên sử dụng API Google Drive để tải tệp đính kèm lên dưới dạng tệp Google Drive và liên kết URI tệp với các tin nhắn tương ứng trong không gian chế độ nhập để nhập tệp đính kèm từ các nền tảng nhắn tin khác nhằm tránh đạt đến giới hạn nội bộ của Google Chat đối với nội dung tải tệp đính kèm lên.

Gói hội viên trước đây

Gói thành viên trước đây là gói thành viên được tạo cho những người dùng đã rời khỏi không gian ban đầu từ nền tảng nhắn tin nguồn nhưng bạn muốn giữ lại dữ liệu của họ trong Chat. Để biết thông tin về cách thêm thành viên mới sau khi không gian không còn ở chế độ nhập, hãy xem bài viết Tạo tài nguyên gói thành viên.

Trong nhiều trường hợp, khi các thành viên trước đây phải tuân thủ chính sách giữ lại dữ liệu trong Google, bạn sẽ muốn giữ lại dữ liệu (chẳng hạn như Tin nhắn và lượt thể hiện cảm xúc) do các thành viên trước đây tạo ra trong một không gian trước khi nhập vào Chat. Khi không gian đang ở chế độ nhập, bạn có thể nhập các gói thành viên trước đây vào không gian bằng cách sử dụng phương thức create trên tài nguyên Membership. Để duy trì thời gian nghỉ của gói thành viên trước đây, bạn phải đặt deleteTime của gói thành viên. Thời gian nghỉ phép này phải chính xác vì thời gian này sẽ ảnh hưởng đến dữ liệu cần giữ lại cho các gói hội viên đó. Hơn nữa, deleteTime này phải sau dấu thời gian tạo không gian và không được là dấu thời gian trong tương lai.

Ngoài deleteTime, bạn cũng có thể đặt createTime để giữ nguyên thời gian tham gia ban đầu của tư cách thành viên trước đây. Không giống như deleteTime, createTime là không bắt buộc. Nếu bạn không đặt chính sách này, createTime sẽ được tự động tính bằng cách trừ đi 1 micrô giây từ deleteTime. Nếu được đặt, createTime phải trước deleteTime và phải vào hoặc sau thời gian tạo không gian. Thông tin createTime này không được dùng để xác định việc giữ lại dữ liệu và sẽ không xuất hiện trong các công cụ dành cho quản trị viên như Bảng điều khiển dành cho quản trị viên của Google và Google Vault.

Mặc dù có thể có nhiều cách để người dùng tham gia và rời khỏi không gian trong nền tảng nhắn tin nguồn (thông qua lời mời, tự tham gia và do người dùng khác thêm vào), nhưng trong Chat, những thao tác đó đều được biểu thị bằng các trường createTime và deleteTime của thành viên trước đây khi được thêm hoặc xoá.

Ví dụ sau đây cho biết cách tạo một thành viên trước đây trong một không gian chế độ nhập:

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)

Thay thế đoạn mã sau:

EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh với thẩm quyền trên toàn miền.
SPACE_NAME: tên của không gian được tạo ở chế độ nhập.
USER_ID: mã nhận dạng duy nhất cho người dùng.

Xác thực tài nguyên đã nhập

Ứng dụng Chat có thể đọc lại và xác thực nội dung của không gian chế độ nhập bằng cách gọi phương thức list trên tài nguyên Message. Bạn có thể đọc các tài nguyên Reaction và Attachment từ bất kỳ trường emojiReactionSummaries và attachment nào của thư được trả về. Các ứng dụng Chat chỉ có thể gọi phương thức này thay mặt cho người dùng bằng cách mạo danh. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Ứng dụng Chat cũng có thể đọc từng tin nhắn để xác thực bằng cách gọi phương thức get trên tài nguyên Message. Các ứng dụng Chat chỉ có thể gọi phương thức này để đọc tin nhắn của chính ứng dụng bằng cách sử dụng thẩm quyền riêng. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Các ứng dụng nhắn tin cũng có thể liệt kê gói thành viên trước đây bằng cách gọi phương thức list trên tài nguyên Membership. Sau khi không gian thoát khỏi chế độ nhập, phương thức list sẽ không hiển thị các gói thành viên trước đây nữa. Các ứng dụng Chat chỉ có thể gọi phương thức này thay mặt cho người dùng bằng cách mạo danh. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Bạn có thể đọc các thuộc tính của không gian chế độ nhập bằng cách gọi phương thức get trên tài nguyên Space. Các ứng dụng nhắn tin chỉ có thể gọi phương thức này bằng thẩm quyền riêng. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Đối chiếu sự khác biệt về tài nguyên đã nhập với dữ liệu nguồn

Nếu bất kỳ tài nguyên đã nhập nào không còn khớp với thực thể ban đầu từ nền tảng nhắn tin nguồn do những thay đổi đối với thực thể ban đầu trong quá trình nhập, thì các ứng dụng trong Chat có thể gọi API Chat để sửa đổi tài nguyên cuộc trò chuyện đã nhập. Ví dụ: nếu người dùng chỉnh sửa một tin nhắn trong nền tảng nhắn tin nguồn sau khi tin nhắn đó được tạo trong Chat, thì các ứng dụng trong Chat có thể cập nhật tin nhắn đã nhập để phản ánh nội dung hiện tại của tin nhắn gốc.

Tin nhắn

Để cập nhật các trường được hỗ trợ trên một thông báo trong không gian chế độ nhập, hãy gọi phương thức update trên tài nguyên Message. Các ứng dụng Chat chỉ có thể gọi phương thức này bằng chính thẩm quyền được dùng trong quá trình tạo tin nhắn ban đầu. Nếu đã sử dụng tính năng nhập vai người dùng trong quá trình tạo thông báo ban đầu, bạn phải sử dụng chính người dùng được mạo danh để cập nhật thông báo đó.

Để xoá một thông báo trong không gian của chế độ nhập, hãy gọi phương thức delete trên tài nguyên Message. Người tạo thông báo gốc không cần phải xoá các thư trong không gian ở chế độ nhập và người dùng có thể xoá các thư này bằng cách mạo danh bất kỳ người dùng nào trong miền. Các ứng dụng nhắn tin chỉ có thể xoá tin nhắn của chính ứng dụng đó bằng thẩm quyền của chính ứng dụng đó. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat.

Lượt thể hiện cảm xúc

Để xoá phản ứng cho một thông điệp trong không gian chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên reactions. Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép các ứng dụng trong Chat.

Phần đính kèm:

Để cập nhật tệp đính kèm cho thư trong không gian chế độ nhập, hãy sử dụng phương thức upload trên tài nguyên media. Để biết thông tin về các phương thức tài nguyên và các loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép các ứng dụng trong Chat.

Gói hội viên trước đây

Để xoá một thành viên trước đây trong không gian chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên Membership. Sau khi một không gian thoát khỏi chế độ nhập, phương thức delete sẽ không cho phép bạn xoá các gói thành viên trước đây nữa.

Bạn không thể cập nhật tư cách thành viên trước đây trong không gian có chế độ nhập. Nếu muốn chỉnh sửa một gói thành viên trước đây được nhập không chính xác, trước tiên, bạn cần xoá gói đó rồi tạo lại khi không gian vẫn đang ở chế độ nhập.

Không gian

Để cập nhật các trường được hỗ trợ trong không gian chế độ nhập, hãy sử dụng phương thức patch trên tài nguyên spaces.

Để xoá không gian của chế độ nhập, hãy sử dụng phương thức delete trên tài nguyên spaces.

Để biết thông tin về các phương thức tài nguyên và loại hỗ trợ xác thực trong không gian chế độ nhập, hãy xem phần Cho phép ứng dụng trong Chat.

Hoàn tất chế độ nhập

Trước khi gọi phương thức completeImport, bạn cần đảm bảo rằng bạn đã hoàn tất quy trình xác thực và điều chỉnh sự khác biệt về tài nguyên. Việc thoát khỏi không gian thoát khỏi chế độ nhập là một quá trình không thể đảo ngược và sẽ chuyển đổi không gian ở chế độ nhập thành không gian thông thường. Không có chỉ báo nào trong Chat cho biết các không gian này là do nhập dữ liệu.

Để hoàn tất chế độ nhập và giúp người dùng có thể truy cập vào không gian, ứng dụng Chat có thể gọi phương thức completeImport trên tài nguyên Space. Các ứng dụng Chat chỉ có thể gọi phương thức này thay mặt cho người dùng thông qua hành vi mạo danh. Để biết thêm thông tin, hãy xem phần Cho phép ứng dụng trong Chat. Người dùng được nhập vai sẽ được thêm vào không gian với tư cách là người quản lý không gian sau khi phương thức này hoàn tất. Phương thức này phải được gọi trong vòng 30 ngày kể từ lần gọi phương thức create.space ban đầu. Nếu bạn cố gắng gọi phương thức này sau khi đã hết thời hạn 30 ngày, thì lệnh gọi sẽ dẫn đến lỗi vì không gian chế độ nhập đã bị xoá và ứng dụng Chat không thể truy cập vào nữa.

Người dùng được nhập vai trong phương thức completeImport không nhất thiết phải là người tạo không gian.

Ví dụ sau đây trình bày cách hoàn tất chế độ nhập:

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)

Thay thế đoạn mã sau:

EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh với thẩm quyền trên toàn miền.
SPACE_NAME: tên của không gian được tạo ở chế độ nhập.

Tạo tài nguyên cho chương trình hội viên

Để thêm thành viên của người dùng cho một không gian đã hoàn tất chế độ nhập, hãy gọi phương thức create trên tài nguyên Membership. Các ứng dụng Chat có thể tiếp tục sử dụng phạm vi chat.import và mạo danh người dùng để gọi phương thức này trong vòng 30 ngày kể từ lệnh gọi phương thức create.space ban đầu. Người dùng được nhập vai phải là người quản lý không gian.

Sau khi hết thời hạn 30 ngày, các ứng dụng trong Chat sẽ yêu cầu thêm phạm vi thành viên để gọi phương thức này.

Các ứng dụng trong Chat nên tạo tài nguyên thành viên ngay sau khi nhập xong để các ứng dụng trong Chat có thể tiếp tục sử dụng phạm vi chat.import để tạo thành viên và cấp cho mọi thành viên quyền truy cập vào không gian đã nhập.