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

Phần sau đây trình bày toàn bộ quy trình nhập:

1. Lập kế hoạch nhập
2. Định cấu hình việc uỷ quyền cho ứng dụng Chat
3. Tạo không gian ở chế độ nhập
4. Nhập tài nguyên
5. Xác thực tài nguyên đã nhập
6. Đối chiếu sự khác biệt về tài nguyên đã nhập với dữ liệu nguồn
7. Hoàn tất chế độ nhập
8. Cấp quyền truy cập vào không gian sau khi nhập chế độ
9. Khắc phục sự cố

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

Lập kế hoạch nhập

Lập kế hoạch sao cho lượng dữ liệu cần được nhập, tìm hiểu cách hạn mức và giới hạn sử dụng có thể ảnh hưởng đến quá trình nhập dữ liệu và tìm hiểu về các loại phòng Chat được hỗ trợ khi nhập vào không gian mới.

Xem xét hạn mức sử dụng API

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

Khi nhập tin nhắn vào một không gian, bạn nên chia sẻ các cuộc gọi đến messages.create() trên các chuỗi thư khác nhau.

Xác định các không gian được hỗ trợ để nhập

Chế độ nhập chỉ hỗ trợ SpaceType của SPACE. Công cụ này không hỗ trợ SpaceType/GROUP_CHAT hoặc DIRECT_MESSAGE. Xem tài liệu cho SpaceType để biết thêm thông tin.

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

Để tạo không gian ở chế độ nhập, hãy gọi phương thức Phương thức create trên Space tài nguyên và đặt importMode thành true.

Khi bạn tạo không gian ở chế độ nhập, hãy lưu ý những điều sau.

• Ngày và giờ - Hãy nhớ, chế độ nhập phải được hoàn tất trong vòng 30 ngày. Nếu không gian vẫn ở chế độ nhập sau 30 giờ ngày kể từ khi phương thức spaces.create() được gọi, tự động bị xoá và không thể truy cập cũng như không thể khôi phục.
  • Không sử dụng giá trị của thuộc tính createTime để theo dõi thời hạn của khung thời gian 30 ngày. Đây không phải là luôn giống như khi bạn gọi phương thức spaces.create(). Thời gian bằng cách sử dụng chế độ nhập, trường createTime có thể được đặt thành dấu thời gian mà không gian được tạo trong nguồn để giữ nguyên thời gian tạo ban đầu.
• Tên tài nguyên của không gian (name) – Giá trị nhận dạng duy nhất dùng để truy xuất thông tin về không gian cụ thể và được tham chiếu trong các bước sau này khi nhập nội dung vào không gian.

Để duy trì thời gian tạo của thực thể không gian tương đương từ nguồn nền tảng nhắn tin, bạn có thể đặt createTime của không gian. Chiến dịch này Bạn phải đặt createTime 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.

Để tạo không gian bên ngoài ở chế độ nhập, hãy đặt externalUserAllowed thành true. Sau khi nhập xong, bạn có thể thêm người dùng bên ngoài.

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

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)

Thay thế đoạn mã sau:

• EMAIL: địa chỉ email của tài khoản người dùng bạn đang mạo danh là một cơ quan có thẩm quyền trên toàn miền.
• DISPLAY_NAME: tên không gian được tạo trong chế độ nhập. Đây phải là tên duy nhất cho không gian được hiển thị với Người dùng Chat. Bạn nên sử dụng tên hiển thị giống với không gian mà từ đó bạn đang nhập dữ liệu.

Nhập tài nguyên

Để nhập tài nguyên từ các nền tảng nhắn tin khác, hãy tạo Google Chat tài nguyên (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 củ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 mà bạn sắp di chuyển khỏi nền tảng thông báo.

Tin nhắn

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

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 đó sẽ bị xoá.

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

Khi bạn tạo thư ở chế độ nhập, không gian sẽ không thông báo hoặc gửi email cho mọi người dùng, bao gồm cả những thông báo có 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:

"""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 bạn đang mạo danh với cơ quan có thẩm quyền trên toàn miền.
• SPACE_NAME: tên cho không gian được tạo ở chế độ nhập.

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

Ứng dụng Chat của bạn có thể nhập phản ứng đối với tin nhắn bằng cách dùng API Chat. Để 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, xem Uỷ quyền ứ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 thông qua API Chat. Để 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, xem Uỷ quyền ứng dụng trong Chat. Tuy nhiên, chúng tôi thực sự khuyên bạn nên sử dụng API Google Drive để tải các tệp đính kèm lên dưới dạng tệp Google Drive và liên kết các URI tệp với thư tương ứng trong không gian chế độ nhập để nhập tệp đính kèm từ nền tảng nhắn tin để tránh đạt đến giới hạn nội bộ của Google Chat cho tệp đính kèm tải lên.

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

Gói thành viên trước đây là gói hội viên được tạo cho những người dùng đã rời khỏi chương trình 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 được 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 những thành viên trong quá khứ phải tuân theo chính sách giữ lại dữ liệu của Google bạn 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) được tạo bởi thành viên trước đây trong một không gian trước khi nhập họ vào Chat. Khi không gian đang ở chế độ nhập, bạn có thể nhập những 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 Membership tài nguyên. Để 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 rời đi này phải chính xác vì thời gian này ảnh hưởng đến việc giữ lại dữ liệu nào cho 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 điểm 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, createTime sẽ được tự động tính bằng lấy deleteTime trừ đi 1 micrô giây. Nếu được đặt, createTime phải trước deleteTime và phải vào đúng hoặc sau thời gian tạo không gian. createTime này thông tin 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 trang quản trị 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 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, được thêm vào của một người dùng khác), thì trong Chat, những hành động đó đều được thể hiện bằng các trường createTime và deleteTime của tư cách thành viên trước đây đang được thêm vào hoặc bị xoá.

Ví dụ sau đây trình bày cách tạo một gói thành viên trước đây trong tệp dữ liệu nhập không gian chế độ:

"""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 bạn đang mạo danh với cơ quan có thẩm quyền trên toàn miền.
• SPACE_NAME: tên cho không gian được tạo ở chế độ nhập.
• USER_ID: mã nhận dạng duy nhất cho người dùng.

Nhập tài nguyên ở không gian bên ngoài

Bạn chỉ có thể tạo không gian bên ngoài bằng chế độ nhập bằng thông tin đăng nhập thuộc về người dùng trong tổ chức Workspace của bạn. Cách này chỉ áp dụng khi không gian đang ở chế độ nhập. Sau khi không gian hoàn tất chế độ nhập, người dùng bên ngoài có thể đã mời tham gia không gian đã nhập (xem phần quyền truy cập) và thông tin đăng nhập của họ để gọi API Chat.

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 Phương thức list trên Message tài nguyên. Bạn có thể đọc các tài nguyên Reaction và Attachment từ bất kỳ thư nào được trả về Trường emojiReactionSummaries và attachment. Ứng dụng trong Chat có thể chỉ 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, xem Uỷ quyền ứng dụng trong Chat.

Ứng dụng Chat cũng có thể đọc từng tin nhắn cho bằng cách gọi hàm Phương thức get trên tài nguyên Message. Các ứng dụng nhắn tin chỉ có thể gọi phương thức này để đọc tin nhắn của chính mình bằng cách bằng thẩm quyền của chính họ. Để biết thêm thông tin, hãy xem Uỷ quyền ứng dụng trong Chat.

Các ứng dụng nhắn tin cũng có thể liệt kê tư cách thành viên trước đây bằng cách gọi Phương thức list trên Membership tài nguyên. Sau khi không gian thoát khỏi chế độ nhập, phương thức list sẽ không hiển thị dữ liệu trong quá khứ gói hội viên nữa. Các ứng dụng Chat chỉ có thể gọi phương thức này trên 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 Uỷ quyền ứ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 Phương thức get trên Space tài nguyên. 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 Uỷ quyền ứ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 tài nguyên được nhập bất kỳ không còn khớp với thực thể ban đầu trong nguồn nền tảng nhắn tin do những thay đổi trong thực thể ban đầu trong quá trình nhập. Các ứng dụng trong Chat có thể gọi API Chat để sửa đổi nội dung đã nhập tài nguyên trò chuyện. Ví dụ: nếu người dùng chỉnh sửa một thông báo trong thông báo nguồn sau khi tin nhắn đó được tạo trong Chat, 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 thư gốc.

Tin nhắn

Cần cập nhật các trường được hỗ trợ trên một thư trong không gian chế độ nhập, hãy gọi phương thức 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 cùng một thẩm quyền được dùng trong quá trình tạo thông báo ban đầu. Nếu bạn đã 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 mạo danh đó để hãy cập nhật tin nhắn đó.

Để xoá thư trong không gian ở chế độ nhập, hãy gọi phương thức Phương thức delete trên Message tài nguyên. Bạn không cần phải xoá thư trong không gian ở chế độ nhập theo tệp gốc người tạo tin nhắn và có thể bị xoá 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 mình bằng cách dùng chính ứng dụng đó cơ quan cấp chứng nhận. Để biết thêm thông tin, hãy xem Uỷ quyền ứng dụng trong Chat.

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

Để xoá lượt thể hiện cảm xúc cho một thư 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à các loại hỗ trợ xác thực trong không gian chế độ nhập, xem Uỷ quyền ứ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 media nguồn. Để biết thông tin về các phương pháp tài nguyên và kiểu xác thực hỗ trợ trong không gian ở chế độ nhập, xem Uỷ quyền ứng dụng trong Chat.

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

Để xoá tư cách 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 Membership tài nguyên. Sau một dấu cách thoát khỏi chế độ nhập, phương thức delete không cho phép bạn xoá dữ liệu cũ gói hội viên 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 bạn muốn để sửa một tư cách thành viên trước đây được nhập không chính xác, bạn cần phải xoá tư cách thành viên đó trước tiên rồi tạo lại khi không gian vẫn đang ở chế độ nhập.

Không gian

Cần 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 ở 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 pháp tài nguyên và các loại hỗ trợ xác thực trong không gian ở chế độ nhập và xem Uỷ quyền ứng dụng trong Chat.

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

Trước khi gọi completeImport phương thức khác, bạn phải đảm bảo rằng xác thực và điều chỉnh những khác biệt về tài nguyên đã hoàn tất. Việc thoát khỏi 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 mà cho rằng những không gian này là do nhập dữ liệu.

Ghi lại ngày và giờ bạn gọi completeImport, tên tài nguyên của người dùng đã thực hiện cuộc gọi và phản hồi được trả về. Thông tin này có thể hữu ích nếu bạn gặp phải vấn đề và phải tìm hiểu về vấn đề đó.

Để 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 trong Chat chỉ có thể gọi phương thức này thay mặt cho người dùng thông qua mạo danh. Để biết thêm thông tin, hãy xem Uỷ quyền ứ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 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ừ thời điểm lệnh 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 phương thức Thời lượng 30 ngày đã trôi qua, cuộc gọi dẫn đến lỗi do quá trình nhập không gian chế độ bị xoá và không thể truy cập vào Ứng dụng Chat.

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 trình bày cách hoàn tất chế độ nhập:

"""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 bạn đang mạo danh với cơ quan có thẩm quyền trên toàn miền.
• SPACE_NAME: tên cho không gian được tạo ở chế độ nhập.

Cấp quyền truy cập vào không gian sau khi nhập chế độ

Cách cấp cho người dùng Chat quyền truy cập vào không gian đã nhập gần đây: Các ứng dụng trong Chat có thể tiếp tục sử dụng phạm vi và người dùng chat.import mạo danh trong vòng 30 ngày kể từ lần gọi phương thức create.space() ban đầu như sau:

• Thêm thành viên vào không gian: Gọi phương thức create() trên tài nguyên Membership. Bạn nên dùng ứng dụng Chat tạo tài nguyên Membership ngay sau khi nhập không gian hoàn tất để các ứng dụng Chat có thể tiếp tục dùng chat.import và đảm bảo rằng tất cả thành viên được nhập đều có quyền truy cập vào .
• Đặt đối tượng mục tiêu: Gọi phương thức update() trên tài nguyên Space. Để tìm hiểu cách tạo và thêm đối tượng mục tiêu, hãy xem Giúp những người dùng cụ thể tìm thấy không gian Google Chat trong tổ chức Google Workspace.

Để sử dụng các phương thức này với phạm vi chat.import, người dùng được nhập vai phải làm người quản lý không gian.

Đối với không gian bên ngoài, gói thành viên Phương thức create() cũng cho phép mời người dùng bên ngoài tổ chức Workspace. Đảm bảo bạn hiểu tất cả các giới hạn đã biết đối với người dùng bên ngoài.

Khắc phục sự cố

Nếu bạn gặp sự cố khi nhập phòng Chat, hãy xem lại các vấn đề sau để được hỗ trợ. Nếu bạn nhận được phản hồi lỗi, hãy ghi chú ghi chú (sao chép/dán văn bản vào tài liệu hoặc lưu ảnh chụp màn hình) cho tài liệu tham khảo và cách khắc phục sự cố sau này.

Khi nhập thành công một không gian, CompleteImportSpace sẽ hoàn tất bằng trạng thái OK.

Không hoàn tất quá trình nhập trước khi hết khoảng thời gian 30 ngày

Như đã mô tả trước đó trong bài viết Tạo không gian ở chế độ nhập, nếu không gian vẫn ở chế độ nhập sau 30 ngày kể từ thời điểm phương thức tạo sẽ tự động bị xoá và không thể truy cập được không thể khôi phục.

Rất tiếc, không gian đã xoá không còn tồn tại hoặc khôi phục được nữa và phải được bắt đầu lại quá trình nhập.

Tìm không gian còn thiếu

Nếu bạn không tìm thấy phòng Chat mới, hãy xem lại bảng dưới đây để xem phản hồi bạn đã nhận được từ CompleteImportSpace gửi đến xem lời giải thích và cách giải quyết.