Tạo và xuất bản nhãn

Tài liệu này mô tả cách tạo và xuất bản nhãn bằng Google Drive Labels API.

Tạo nhãn

Để tạo nhãn, hãy sử dụng phương thức create trên tài nguyên labels. Nhãn có thể tuỳ ý chứa một hoặc nhiều đối tượng Field.

Bạn cũng phải chỉ định:

  • Một đối tượng LabelType.

  • Một nhãn title thông qua đối tượng Properties.

  • Tham số truy vấn useAdminAccess được đặt thành true để sử dụng thông tin đăng nhập quản trị viên của người dùng. Trước khi cấp quyền truy cập, máy chủ sẽ xác minh để đảm bảo rằng người dùng có đặc quyền quản trị Quản lý nhãn phân loại bắt buộc.

Mã mẫu sau đây cho biết cách dùng phương thức create để tạo nhãn tiêu chuẩn của quản trị viên có tiêu đề được chỉ định và một SelectionOptions Field có 2 đối tượng Choice.

Python

label_body = {
    'labelType': 'ADMIN',
    'properties': {
        'title': 'TITLE'
    },
    'fields': [{
        'properties': {
            'displayName': 'DISPLAY_NAME'
        },
        'selectionOptions': {
            'listOptions': {},
            'choices': [{
                'properties': {
                    'displayName': 'CHOICE_1'
                }
            }, {
                'properties': {
                    'displayName': 'CHOICE_2'
                }
            }]
        }
    }]
}
response = service.labels().create(
    body=label_body, useAdminAccess=True).execute()

Node.js

var label = {
  'labelType': 'ADMIN',
  'properties': {
    'title': 'TITLE'
  },
  'fields': [{
    'properties': {
      'displayName': 'DISPLAY_NAME'
    },
    'selectionOptions': {
      'listOptions': {},
      'choices': [{
        'properties': {
          'displayName': 'CHOICE_1'
        }
      }, {
        'properties': {
          'displayName': 'CHOICE_2'
        }
      }]
    }
  }]
};

service.labels.create({
  requestBody: label,
  useAdminAccess: true
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Thay thế nội dung sau:

  • TITLE: Tiêu đề của nhãn.
  • DISPLAY_NAME: Tên hiển thị của trường.
  • CHOICE_1: Lựa chọn đầu tiên trong trường SelectionOptions.
  • CHOICE_2: Lựa chọn thứ hai trong trường SelectionOptions.

Nhãn được tạo trong UNPUBLISHED_DRAFT State. Nhãn phải là PUBLISHED thì người dùng mới nhìn thấy và sử dụng được trên tệp. Để biết thêm thông tin, hãy xem phần Vòng đời của nhãn.

Hạn mức về nhãn

Các giới hạn sau đây áp dụng khi tạo và áp dụng nhãn:

  • Nhãn tiêu chuẩn: 150
  • Số trường trên mỗi nhãn: 10

Làm việc với các trường trong nhãn

Bảng sau đây mô tả các loại trường mà bạn có thể thêm vào nhãn, cách người dùng tương tác với các trường đó, cũng như các điểm cần lưu ý và giới hạn về định dạng:

Field Type Những việc người dùng có thể làm Những điểm cần lưu ý và giới hạn về định dạng
SelectionOptions Chọn một hoặc nhiều lựa chọn trong danh sách Số lượng lựa chọn tối đa được hỗ trợ là 200
Số lượng lựa chọn tối đa cho một tệp là 10 như được định cấu hình trong ListOptions
IntegerOptions Nhập một giá trị bằng số Chỉ hỗ trợ số nguyên
DateOptions Chọn một ngày trên lịch (Không bắt buộc) Bạn có thể đặt DateFormat thành "Long: Month DD, YYYY" (Dài: Tháng DD, YYYY) hoặc "Short: MM/DD/YY" (Ngắn: MM/DD/YY)
TextOptions Nhập văn bản vào hộp văn bản Số ký tự tối đa được hỗ trợ là 100
UserOptions Chọn một hoặc nhiều người dùng trong danh bạ Google Workspace. Số lượng mục nhập tối đa của người dùng cho một tệp là 10 như được định cấu hình trong ListOptions

Xuất bản nhãn

Drive Labels API cho phép bạn xuất bản nhãn nháp sau khi hoàn tất. Sau đó, người dùng sẽ thấy nhãn này và có thể áp dụng cho các tệp.

Để xuất bản nhãn, hãy sử dụng phương thức publish trên tài nguyên labels và chỉ định:

  • Một tài nguyên labels đại diện cho mọi nhãn. Nó chứa một tài nguyên name và một id. Đây là giá trị nhận dạng riêng biệt trên toàn cầu cho nhãn.

  • Tham số truy vấn useAdminAccess được đặt thành true để sử dụng thông tin đăng nhập quản trị viên của người dùng. Trước khi cấp quyền truy cập, máy chủ sẽ xác minh để đảm bảo rằng người dùng có đặc quyền quản trị Quản lý nhãn phân loại bắt buộc.

Mã mẫu sau đây cho biết cách sử dụng id của nhãn để xác định và xuất bản nhãn chính xác.

Python

service.labels().publish(
    name='labels/ID',
    body={
        'useAdminAccess': True
    }
).execute()

Node.js

service.labels.publish({
  name: 'labels/ID',
  requestBody: {
    useAdminAccess: true
  }
}, (err, res) => {
  if (err) return console.error('The API returned an error: ' + err);
  console.log(res);
});

Thay thế ID bằng mã nhận dạng của nhãn cần xuất bản.

Sau khi được xuất bản, nhãn sẽ chuyển sang PUBLISHED State và mã sửa đổi của nhãn sẽ tăng lên. Sau đó, người dùng sẽ thấy nhãn này và có thể áp dụng cho các tệp. Để biết thêm thông tin, hãy xem phần Vòng đời của nhãn.

Các ràng buộc khi xuất bản nhãn

Khi bạn chuẩn bị xuất bản nhãn, hãy lưu ý những hạn chế sau:

  • Sau khi xuất bản, nhãn không thể trở về trạng thái nháp ban đầu. Để biết thêm thông tin, hãy xem phần Vòng đời của nhãn.

  • Việc xuất bản nhãn sẽ tạo ra một bản sửa đổi mới được xuất bản. Tất cả các bản sửa đổi nháp trước đó đều bị xoá. Các bản sửa đổi đã xuất bản trước đó vẫn được giữ lại nhưng có thể bị xoá tự động nếu cần.

  • Sau khi xuất bản, bạn sẽ không được phép thực hiện một số thay đổi. Nhìn chung, điều này có nghĩa là mọi thay đổi làm mất hiệu lực hoặc kích hoạt các quy định hạn chế mới đối với siêu dữ liệu hiện có liên quan đến nhãn đều bị từ chối. Ví dụ: Bạn không được phép thực hiện những thay đổi sau đây đối với nhãn sau khi nhãn được xuất bản:

    • Nhãn sẽ bị xoá ngay lập tức. (Bạn phải tắt tính năng này trước rồi mới xoá được.)
    • Field.FieldType đã thay đổi.
    • Nội dung cập nhật đối với các lựa chọn xác thực Field sẽ từ chối một số nội dung từng được chấp nhận trước đây.
    • Giảm số lượng mục nhập tối đa.