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, phản ứng, gói thành viên và thực thể không gian hiện có từ các nền tảng nhắn tin khác vào các tài nguyên tương ứng của API Chat. Bạn có thể nhập dữ liệu này bằng cách tạo phòng Chat ở chế độ nhập rồi nhập dữ liệu vào các phòng trò chuyện đó.

Dưới đây là thông tin tổng quan về các bước liên quan đến việc nhập dữ liệu bằng cách sử dụng không gian cho chế độ nhập:

Xem lại 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ều chỉnh sự khác biệt về tài nguyên đã nhập so với dữ liệu nguồn.
Hoàn tất chế độ nhập.
Tạo tài nguyên về 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 ứng dụng Chat, hãy làm theo phần quickstart nà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 đã phát hành trong Chat. Để tạo và phát hành ứng dụng Chat, hãy xem nội dung Tạo ứng dụng Google Chat.
Đã định cấu hình hoạt động 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, xem phần Uỷ quyền ứng dụng trong Chat.

Xem 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ể thay đổi đáng kể tuỳ thuộc vào lượng tài nguyên Chat cần nhập. 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. Để duy trì 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 mà bạn tạo để có thể tham khảo trong các bước sau khi nhập nội dung vào không gian đó.

Từ thời điểm phương thức create được gọi, các ứng dụng trong Chat sẽ 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 nhắn tin vẫn có thể tạo 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, không gian đó sẽ tự động bị xoá và ứng dụng Chat sẽ không truy cập được và không thể khôi phục được. Hãy lên kế hoạch trước bằng cách xem lại giới hạn sử dụng của ứng dụng Chat để đảm bảo mọi tài nguyên đã lên lịch đều có thể nhập vào Chat trong khung thời gian này.

Ví dụ sau đây cho biết cách tạo 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ế các đ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.

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 sẽ 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ứa chế độ nhập. Khi tạo tài nguyên trong không gian, bạn sẽ chỉ định dữ liệu từ tài nguyên liên quan từ nền tảng thông báo mà bạn sẽ di chuyển.

Tin nhắn

Các ứng dụng nhắn tin của bạn có thể nhập tin nhắn bằng cách dùng thẩm quyền của chính mình hoặc thay mặt người dùng thông qua hình thức mạo danh. (Tác giả thư được đặt thành tài khoản người dùng bị mạo danh.) Để biết thêm thông tin, hãy xem bài viết Uỷ quyền cho ứng dụng trong Chat. Để nhập tin nhắn trong không gian của chế độ nhập, hãy gọi phương thức create trên tài nguyên Message. Để duy trì thời gian tạo thông báo gốc trên 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ị trong khoảng thời gian tạo không gian mà bạn đã đặt trước đó cho đến thời gian hiện tại.

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

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 thông báo ở chế độ nhập, các 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ả những tin nhắn có chứa lượt đề cập của người dùng.

Ví dụ sau đây cho biết cách tạo thông báo trong không gian có 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ế các đ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 toàn 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 bài viết Uỷ quyền cho ứng dụng trong Chat.

Phần đính kèm:

Ứng dụng Chat của bạn 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 bài viết Uỷ quyền cho ứng dụng trong Chat.

Gói thành 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 thực thể 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 phần Tạo tài nguyên thành viên.

Trong nhiều trường hợp, khi các thành viên cũ phải tuân thủ chính sách giữ lại dữ liệu trong Google, bạn nên lưu giữ 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 chúng vào Chat. Khi không gian đang ở chế độ nhập, bạn có thể nhập các 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 rời khỏi 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 rời đi này phải chính xác vì nó sẽ ảnh hưởng đến dữ liệu được giữ lại để dùng 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ữ lại thời gian tham gia ban đầu của gói 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, thì createTime sẽ tự động được 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 về createTime này không dùng để xác định hoạt động giữ lại dữ liệu và sẽ không hiển thị 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ó nhiều cách để người dùng có thể 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), nhưng trong Chat, tất cả các hành động đó đều được thể hiện bằng các trường createTime và deleteTime trước đây của thành viên được thêm hoặc bị xoá.

Ví dụ sau đây cho biết cách tạo gói thành viên trước đây trong 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ế các đ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 toàn 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 của 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ừ trường emojiReactionSummaries và attachment của bất kỳ thông báo trả về nào. Các ứng dụng trong 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 bài viết 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 trong 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 bài viết Uỷ quyền cho ứng dụng trong Chat.

Các ứng dụng trong Chat cũng có thể liệt kê những 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 trong 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 bài viết Uỷ quyền cho ứng dụng trong Chat.

Bạn có thể đọ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 trong Chat 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 bài viết Uỷ quyền cho ứng dụng trong Chat.

Điều chỉnh 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 thay đổi của 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 của chế độ nhập, hãy gọi phương thức update trên tài nguyên Message. Các ứng dụng trong Chat chỉ có thể gọi phương thức này bằng cùng một thẩm quyền đã dùng trong quá trình tạo thông báo ban đầu. Nếu đã sử dụng tính năng mạo danh 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 nhập vai đó để cập nhật thông báo đó.

Để xoá 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 tin nhắn ban đầu không nhất thiết phải xoá tin nhắn trong không gian ở chế độ nhập và có thể xoá tin nhắn 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 chính quyền. Để biết thêm thông tin, hãy xem bài viết Uỷ quyền cho ứng dụng trong Chat.

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

Để xoá biểu tượng cảm xúc cho một tin nhắn trong không gian của 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 bài viết Uỷ quyền cho ứ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 kiểu xác thực được hỗ trợ trong không gian chế độ nhập, hãy xem bài viết Cho phép ứng dụng trong Chat.

Gói thành viên trước đây

Để xoá thành viên trước đây trong một không gian của 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á 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 ở chế độ nhập. Nếu muốn sửa thành viên trong quá khứ được nhập không chính xác, trước tiên, bạn cần xoá thành viên đó 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 của chế độ nhập, hãy sử dụng phương thức patch trên tài nguyên spaces.

Để xoá một không gian cho 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à các kiểu xác thực được hỗ trợ trong không gian chế độ nhập và xem bài viết Uỷ quyền cho ứng dụng trong Chat.

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

Trước khi gọi phương thức completeImport, bạn nên đảm bảo đã hoàn tất việc xác thực và điều chỉnh các điểm khác biệt về tài nguyên. Việc thoát khỏi một không gian khỏi chế độ nhập là một quá trình không thể đảo ngược và 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 có thể phân bổ các không gian này cho một lượt 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 nhắn tin 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 bài viết Uỷ quyền cho ứng dụng trong Chat. Người dùng mạo danh 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 thời hạn 30 ngày đã trôi qua, 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 còn truy cập được nữa.

Người dùng được mạo danh trong phương thức completeImport không cần phải là người tạo không gian.

Ví dụ sau đây cho biết 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ế các đ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 toàn 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 dành cho hội viên

Để thêm tư cách 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 nhắn tin có thể tiếp tục sử dụng phạm vi chat.import và chế độ mạo danh người dùng để gọi phương thức này trong vòng 30 ngày kể từ khi gọi phương thức create.space ban đầu. Người dùng được mạo danh phải là người quản lý không gian.

Sau khi thời hạn 30 ngày trôi qua, 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 Chat nên tạo tài nguyên thành viên ngay sau khi quá trình nhập hoàn tất. Nhờ đó, 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 cũng như cung cấp cho mọi thành viên quyền truy cập vào không gian đã nhập.