API Enterprise License Manager: Hướng dẫn dành cho nhà phát triển

Tài liệu này mô tả cách quản trị viên của đại lý và cấp tài khoản có thể sử dụng API Enterprise License Manager để quản lý việc chỉ định giấy phép của người dùng. Sau khi giấy phép SKU sản phẩm của tài khoản được bật và người dùng của bạn đã được tạo, hãy sử dụng API Enterprise License Manager để chỉ định, cập nhật, truy xuất và xoá giấy phép cho người dùng trong tài khoản của bạn.

Trong phiên bản này, các quản trị viên tài khoản và đại lý sử dụng API Enterprise License Manager. Quản trị viên được uỷ quyền có đặc quyền License Management cũng có thể sử dụng API Enterprise License Manager.

Lưu ý: API Enterprise License Manager được khách hàng của Google sử dụng. Để biết thông tin về cách nhà phát triển ứng dụng bên thứ ba của Google quản lý giấy phép, hãy xem API Google Workspace Marketplace.

API Enterprise License Manager dựa trên phương pháp thiết kế Chuyển trạng thái đại diện (RESTful) cho các dịch vụ web.

Quản lý giấy phép

Cấp phép

Trước khi thực hiện thao tác này, khách hàng hoặc đại lý đã đặt mua giấy phép sản phẩm của Google và tạo người dùng. Để chỉ định một trong các giấy phép sản phẩm này cho người dùng này, hãy sử dụng yêu cầu HTTP POST sau. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Đối với mã sản phẩm và mã SKU, hãy xem các Sản phẩm và SKU hiện có của API: 

POST https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user

Lưu ý: Bạn có thể cấp giấy phép cho nhiều sản phẩm của Google cho người dùng. Tuy nhiên, tại một thời điểm, người dùng chỉ được cấp một giấy phép SKU cho mỗi sản phẩm. Bằng cách sử dụng API, giấy phép SKU của người dùng có thể được chỉ định lại thành giấy phép SKU khác trong sản phẩm.

Ví dụ này chỉ định SKU Google-Drive-storage-20GB cho người dùng có địa chỉ email chính là alex@example.com: 

POST https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user

Nội dung yêu cầu JSON: 

{
  "userId" : "alex@example.com",
}

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API. Nếu thành công, phản hồi sẽ trả về trạng thái chỉ định cấp phép ở định dạng dữ liệu JSON.

Phản hồi JSON 

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-20GB",
  "skuName": "Google Drive storage 20 GB",
  "productName": "Google Drive storage"
}

Để biết thêm thông tin, hãy xem trang tham khảo về phương thức chèn của LicenseAssignments.

Chỉ định lại SKU của sản phẩm với một SKU khác trong cùng sản phẩm

Để chỉ định lại giấy phép của người dùng cho một SKU giấy phép mới trong cùng một sản phẩm, hãy sử dụng yêu cầu HTTP PUT sau. API này cũng hỗ trợ cú pháp bản vá. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Đối với mã sản phẩm và mã SKU, hãy xem các Sản phẩm và SKU hiện có của API: 

PUT https://www.googleapis.com/apps/licensing/v1/product/productId/sku/the current skuId/user/user's email

Ví dụ này cập nhật SKU Google-Drive-storage-20GB hiện tại với Google-Drive-storage-50GB. SKU giấy phép hiện tại nằm trong URI của yêu cầu và SKU giấy phép mới nằm trong phần nội dung của yêu cầu: 

PUT https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-20GB/user/alex@example.com

Nội dung yêu cầu JSON có :

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API. Nếu thành công, phản hồi sẽ trả về trạng thái chỉ định giấy phép ở định dạng dữ liệu JSON.

Phản hồi JSON 

{
  "kind": "licensing#licenseAssignment",
  "etags": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "alex@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

Để biết thêm thông tin, hãy xem các trang tham khảo về phương pháp cập nhật và phương pháp vá lỗi của LicenseAssignments.

Truy xuất tất cả người dùng đã chỉ định giấy phép cho một sản phẩm cụ thể

Để lấy tất cả giấy phép người dùng cho một sản phẩm cụ thể, hãy sử dụng yêu cầu HTTP GET sau. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Chuỗi truy vấn customerId là tên miền chính của khách hàng. Chuỗi truy vấn maxResults xác định số lượng mục nhập giấy phép người dùng được trả về trong phản hồi của API:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/users?customerId=primary domain name&maxResults=max results per page

Đối với mã sản phẩm và mã SKU, hãy xem phần Sản phẩm và SKU hiện có của API.

Ví dụ này liệt kê trang kết quả đầu tiên cho tất cả người dùng trong miền example.com được cấp giấy phép cho sản phẩm bộ nhớ Google-Drive:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/users?customerId=example.com&maxResults=2

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API. Nếu thành công, phản hồi sẽ trả về danh sách cấp phép ở định dạng JSON.

Phản hồi JSON

{
  "kind" : "licensing#licenseAssignmentList",
  "etag": "etag value",
  "nextPageToken" : "the next page token value",
  "items": [
  {
    "kind": "licensing#licenseAssignment",
    "etags": "etag value",
    "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
    "userId": "alex@example.com",
    "productId": "Google-Drive-storage",
    "skuId": "Google-Drive-storage-50GB",
    "skuName": "Google Drive storage 50 GB",
    "productName": "Google Drive storage"
  },
  {
    "kind": "licensing#licenseAssignment",
    "etags": "etag value",
    "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/keshav@example.com",
    "userId": "keshav@example.com",
    "productId": "Google-Drive-storage",
    "skuId": "Google-Drive-storage-200GB",
    "skuName": "Google Drive storage 200 GB",
    "productName": "Google Drive storage"
  },
  ...
}

Để biết thêm thông tin, hãy xem trang tham khảo phương pháp listForProduct của LicenseAssignments.

Truy xuất tất cả người dùng đã chỉ định giấy phép cho một SKU sản phẩm cụ thể

Để nhận danh sách tất cả người dùng có giấy phép cho một SKU sản phẩm cụ thể, hãy sử dụng yêu cầu HTTP GET sau. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Chuỗi truy vấn customerId là tên miền chính của khách hàng. Chuỗi truy vấn maxResults xác định số lượng mục nhập của người dùng được trả về trong phản hồi của API:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/users?customerId=primary domain name&maxResults=max results per response page

Để biết mã sản phẩm và mã SKU, hãy xem Sản phẩm và SKU có sẵn của API

Ví dụ này trả về trang đầu tiên của tất cả người dùng trong miền example.com được chỉ định giấy phép cho SKU Google-Drive-storage-200GB. Phản hồi liệt kê hai mục nhập của người dùng trên mỗi trang:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/users?customerId=example.com&maxResults=2

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API. Nếu thành công, phản hồi sẽ trả về danh sách cấp phép ở định dạng JSON.

Phản hồi JSON

{
  "kind" : "licensing#licenseAssignmentList",
   "etag": "etag value",
   "nextPageToken" : "next page token's value",
   "items": [
    {
     "kind": "licensing#licenseAssignment",
     "etags": "etag value",
     "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/alex@example.com",
     "userId": "alex@example.com",
     "productId": "Google-Drive-storage",
     "skuId": "Google-Drive-storage-200GB",
     "skuName": "Google Drive storage 200 GB",
     "productName": "Google Drive storage"
    },
    {
     "kind": "licensing#licenseAssignment",
     "etags": "etag value",
     "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-200GB/user/mary@example.com",
     "userId": "mary@example.com",
     "productId": "Google-Drive-storage",
     "skuId": "Google-Drive-storage-200GB",
     "skuName": "Google Drive storage 200 GB",
     "productName": "Google Drive storage"
    },
    ...
  }

Để biết thêm thông tin, hãy xem trang tham khảo phương pháp listForProductAndSku của giấy phép.

Truy xuất giấy phép của người dùng cụ thể theo SKU của sản phẩm

Để nhận giấy phép của một người dùng cụ thể theo SKU của sản phẩm, hãy sử dụng yêu cầu HTTP GET sau. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Đối với mã sản phẩm và mã SKU, hãy xem các Sản phẩm và SKU hiện có của API:

GET https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user/userId

Ví dụ này sẽ nhận SKU sản phẩm 50 GB của bộ nhớ Google Drive cho người dùng có userId là alex@example.com:

GET https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com

Nếu người dùng có giấy phép này, thì đó là phản hồi thành công và là mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API. Nếu thành công, phản hồi sẽ trả về giấy phép của người dùng ở định dạng JSON.

Phản hồi JSON

{
  "kind": "licensing#licenseAssignment",
  "etag": "etag value",
  "selfLink": "https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com",
  "userId": "keshav@example.com",
  "productId": "Google-Drive-storage",
  "skuId": "Google-Drive-storage-50GB",
  "skuName": "Google Drive storage 50 GB",
  "productName": "Google Drive storage"
}

Để biết thêm thông tin, hãy xem trang tham khảo phương thức nhận của LicenseAssignments.

Xoá giấy phép

Để bỏ chỉ định giấy phép cho một người dùng, hãy sử dụng yêu cầu HTTP DELETE sau. Bao gồm tiêu đề Authorization như mô tả trong phần Uỷ quyền cho yêu cầu. Đối với mã sản phẩm và mã SKU, hãy xem các Sản phẩm và SKU hiện có của API:

DELETE https://www.googleapis.com/apps/licensing/v1/product/productId/sku/skuId/user/userId

Trong ví dụ sau, giấy phép Google-Drive-storage-50GB được bỏ chỉ định cho người dùng có userId là alex@example.com:

DELETE https://www.googleapis.com/apps/licensing/v1/product/Google-Drive-storage/sku/Google-Drive-storage-50GB/user/alex@example.com

Phản hồi thành công sẽ trả về mã trạng thái HTTP 200. Để biết các mã lỗi có thể xảy ra, hãy xem Mã lỗi của API.

Để biết thêm thông tin, hãy xem trang tham khảo phương thức xoá LicenseAssignments.

Mã lỗi

Nếu yêu cầu không thành công, thì phản hồi sẽ có phần giải thích ngắn gọn về lỗi đó:

Mã lỗi Nội dung mô tả
400 Yêu cầu không hợp lệ – Email của người dùng không hợp lệ.
400 Yêu cầu không hợp lệ – SKU/sản phẩm không tồn tại.
401 Người thực hiện không có thông tin xác thực để gọi API này.
404 Nếu người dùng không có giấy phép này thì phản hồi sẽ có mã lỗi "not found" (không tìm thấy).
412 Chưa đáp ứng được điều kiện tiên quyết. Để biết thông tin chi tiết về lỗi này, hãy xem trường message. Ví dụ:
  • Auto License switching is not allowed.
  • Auto License un-assignment is not allowed.
  • For reassign operations, the new SKU should be different from the old SKU: sku
  • Reassign operation can't be performed on different products: product1, product2
  • Reassign operation can't be performed on different users: user1, user2
  • There aren't enough available licenses for the specified product-SKU pair
  • User already has a license for the specified product and SKU
  • User already has a license of the product, but with a different SKU. To reassign a new SKU for this product, use the 'update' operation.
503 Dịch vụ Trình quản lý giấy phép không hoạt động.