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

Với Google Chat API, 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 các 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ể 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 không gian Chat ở chế độ nhập và nhập dữ liệu vào các không gian đó. Sau khi quá trình này hoàn tất, các không gian này sẽ trở thành phòng Chat tiêu chuẩn.

Sau đây là quy trình nhập đầy đủ:

1. Lập kế hoạch nhập
2. Định cấu hình quyền 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 sử dụng chế độ nhập
9. Khắc phục sự cố

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

Lập kế hoạch nhập

Hãy lên kế hoạch cho lượng dữ liệu cần nhập, tìm hiểu cách giới hạn và hạn mức sử dụng có thể ảnh hưởng đến quy trình nhập, đồng thời lưu ý các loại không gian Chat được hỗ trợ khi nhập vào một không gian mới.

Xem lại giới hạn sử dụng API

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 số lượng tài nguyên Chat cần nhập. Xem lại 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.

Khi nhập tin nhắn vào không gian, bạn nên phân phối các lệnh gọi đến phương thức messages.create() trên nhiều chuỗi tin nhắn.

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

Chế độ nhập chỉ hỗ trợ SpaceType của SPACE và GROUP_CHAT. Tệp này không hỗ trợ DIRECT_MESSAGE. Hãy xem tài liệu về SpaceType để biết thêm thông tin.

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.

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ớ hoàn tất chế độ nhập trong vòng 30 ngày. Nếu không gian vẫn ở chế độ nhập sau 30 ngày kể từ khi phương thức spaces.create() được gọi, thì không gian đó sẽ tự động bị xoá và không thể truy cập cũng như khôi phục được.
  • Không sử dụng giá trị của trường createTime để theo dõi thời điểm hết hạn của khung thời gian 30 ngày. Điều này không phải lúc nào cũng giống như khi bạn gọi phương thức spaces.create(). Khi sử dụng chế độ nhập, bạn có thể đặt trường createTime thành dấu thời gian trước đây tại thời điểm tạo không gian trong nguồn để giữ nguyên thời gian tạo ban đầu.
• Tên tài nguyên 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.

Để giữ nguyên thời gian tạo của thực thể không gian tương đương từ nền tảng nhắn tin 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 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 hoàn tất quá trình nhập, bạn có thể thêm người dùng bên ngoài.

Ví dụ sau đây cho thấy cách tạo 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ế nội dung sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có quyền trên toàn miền.
• DISPLAY_NAME: tên của không gian được tạo ở chế độ nhập. Đây phải là tên duy nhất cho không gian mà người dùng Chat nhìn thấy. Bạn nên sử dụng tên hiển thị giống với tên của không gian mà 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, 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 từ tài nguyên liên quan trên nền tảng nhắn tin mà bạn đang di chuyển.

Tin nhắn

Ứng dụng Chat của bạn có thể nhập tin nhắn bằng quyền của riêng ứng dụng hoặc thay mặt cho người dùng thông qua tính năng mạo danh. Tác giả thư được đặt thành tài khoản người dùng được mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng 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. Để giữ nguyên thời gian tạo của thư gốc từ nền tảng nhắn tin nguồn, bạn có thể đặt createTime của thư. Bạn phải đặt createTime này thành một giá trị nằm trong khoảng 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ó cùng thời gian đó đã bị xoá.

Những tin nhắn chứa URL của bên thứ ba trong các phòng ở 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, 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, bao gồm cả những tin nhắn chứa tính năng nhắc đến người dùng.

Ví dụ sau đây cho thấy 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ế nội dung sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có 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ủa bạn có thể nhập phản ứng cho 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 Uỷ quyền cho ứng dụng 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 Uỷ quyền cho ứng dụng 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 thư 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 việc 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à các 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 trên 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. Để giữ nguyên 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 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 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 không được đặt, createTime sẽ được tự động tính toán bằng cách trừ 1 micro giây khỏi 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, được người dùng khác thêm), nhưng trong Chat, tất cả các hành động đó đều được biểu thị bằng các trường createTime và deleteTime về tư cách thành viên trước đây dưới dạng được thêm hoặc bị xoá.

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

"""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ế nội dung sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có 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.

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 ở chế độ nhập bằng thông tin xác thực thuộc về người dùng trong tổ chức Workspace của bạn. Điều 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, bạn có thể mời người dùng bên ngoài tham gia các không gian đã nhập (xem mục truy cập) và sử dụng thông tin xác thực của họ để gọi Chat API.

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 tài nguyên Reaction và Attachment từ trường emojiReactionSummaries và attachment của bất kỳ thông báo nào được trả về. Ứng dụng trò chuyện chỉ có thể gọi phương thức này thay mặt người dùng thông qua hoạt động mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng 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. Ứng dụng trò chuyện 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 quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Ứng dụng trò chuyện cũng có thể liệt kê các 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. Ứng dụng trò chuyện chỉ có thể gọi phương thức này thay mặt cho người dùng thông qua việc mạo danh. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng 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. Ứng dụng trò chuyện chỉ có thể gọi phương thức này bằng quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

Điều chỉnh sự khác biệt về tài nguyên đã nhập từ dữ liệu nguồn

Nếu bất kỳ tài nguyên nào đã nhập không còn khớp với thực thể ban đầu từ nền tảng nhắn tin nguồn do các thay đổi trong thực thể ban đầu trong quá trình nhập, thì ứng dụng Chat có thể gọi Chat API để sửa đổi tài nguyên 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. Ứng dụng trò chuyện chỉ có thể gọi phương thức này bằng chính quyền đã được sử 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 ở 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. Ứng dụng trò chuyện chỉ có thể xoá tin nhắn của chính mình bằng quyền của riêng ứng dụng. Để biết thêm thông tin, hãy xem phần Uỷ quyền cho ứng dụng Chat.

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

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

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

Để xoá gói 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 gói thành viên cũ đã nhập không chính xác, trước tiên, bạn cần xoá gói thành viên đó rồi tạo lại gói thành viên đó trong khi không gian vẫn ở 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 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 Uỷ quyền ứng dụng 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 quá 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 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 cho biết các không gian này được phân bổ cho một lượt 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 lệnh gọi và phản hồi được trả về. Điều này có thể hữu ích nếu bạn gặp phải vấn đề và phải điều tra 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. Ứng dụng trò chuyện chỉ có thể thay mặt người dùng gọi phương thức này thông qua việc 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 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 khoảng thời gian 30 ngày đã trôi qua, thì lệnh gọi sẽ không thành công vì không gian chế độ nhập bị xoá và ứng dụng Chat không thể 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 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ế nội dung sau:

• EMAIL: địa chỉ email của tài khoản người dùng mà bạn đang mạo danh có quyền trên toàn miền.
• SPACE_NAME: tên của 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

Để cấp cho người dùng Chat quyền truy cập vào không gian mới nhập gần đây, các ứng dụng Chat có thể tiếp tục sử dụng phạm vi chat.import và hoạt động mạo danh người dùng trong vòng 30 ngày kể từ lệnh gọi phương thức create.space() ban đầu để thực hiện những việc 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. Các ứng dụng Chat nên tạo tài nguyên Membership ngay sau khi quá trình nhập không gian hoàn tất để có thể tiếp tục sử dụng phạm vi 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 không gian.
• Đặ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 bài viết Giúp những người dùng cụ thể trong tổ chức Google Workspace có thể tìm thấy không gian Google Chat.

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

Đối với không gian bên ngoài, phương thức create() về tư cách thành viên cũng cho phép mời người dùng bên ngoài tổ chức Workspace của bạn. Hãy đảm bảo bạn hiểu rõ tất 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 vấn đề khi nhập phòng Chat, hãy xem các vấn đề sau để được hỗ trợ. Nếu bạn gặp một phản hồi lỗi, hãy ghi lại phản hồi đó (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) để tham khảo và khắc phục sự cố sau này.

Khi một không gian được nhập thành công, CompleteImportSpace sẽ hoàn tất với trạng thái là OK.

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

Như mô tả trước đó trong phần 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 được gọi, thì không gian đó sẽ tự động bị xoá và không thể truy cập cũng như khôi phục được.

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

Tìm dấu cách bị thiếu

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