API Cài đặt dành cho quản trị viên cho phép quản trị viên của các miền Google Workspace truy xuất và thay đổi chế độ cài đặt của miền ở dạng nguồn cấp dữ liệu Google Data API.
Các chế độ cài đặt miền này bao gồm nhiều tính năng có trong Bảng điều khiển dành cho quản trị viên Google Workspace. Ví dụ về cách sử dụng API này là tạo bảng điều khiển tuỳ chỉnh hoặc tích hợp các miền Google Workspace vào môi trường cũ hiện có.
API Cài đặt dành cho quản trị viên triển khai giao thức Google Data API. Google Data API tuân thủ mô hình chỉnh sửa và xuất bản Giao thức xuất bản Atom (AtomPub). Các yêu cầu HTTP AtomPub sử dụng phương pháp thiết kế Chuyển trạng thái đại diện (RESTful) cho các dịch vụ web. Để biết thêm thông tin, hãy xem Hướng dẫn dành cho nhà phát triển về Google Data API.
Đối tượng
Tài liệu này dành cho các nhà phát triển muốn viết ứng dụng khách có thể sửa đổi và truy xuất thông tin về các miền Google Workspace. Tài liệu này cung cấp các ví dụ về hoạt động tương tác cơ bản của API Cài đặt dành cho quản trị viên bằng XML và HTTP thô.
Tài liệu này giả định rằng bạn hiểu các ý tưởng chung đằng sau the giao thức Google Data API và đã quen thuộc với Bảng điều khiển dành cho quản trị viên Google Workspace. Để biết thêm thông tin về Bảng điều khiển dành cho quản trị viên, hãy xem bài viết Sử dụng Bảng điều khiển dành cho quản trị viên.
Bắt đầu
Để bắt đầu sử dụng API Cài đặt dành cho quản trị viên, trước tiên, hãy thiết lập tài khoản.
Tạo tài khoản
API Cài đặt dành cho quản trị viên được bật cho các tài khoản Google Workspace. Đăng ký tài khoản Google Workspace cho mục đích thử nghiệm. Dịch vụ Cài đặt dành cho quản trị viên sử dụng Google Accounts. Vì vậy, nếu bạn đã có tài khoản trên một miền Google Workspace, thì bạn đã sẵn sàng.
Giới thiệu về các loại nguồn cấp dữ liệu của API Cài đặt dành cho quản trị viên
API Cài đặt dành cho quản trị viên cho phép bạn quản lý các danh mục chế độ cài đặt miền sau:
- Chế độ cài đặt Đăng nhập một lần
- Tính năng Đăng nhập một lần (SSO) dựa trên SAML cho phép người dùng sử dụng cùng một thông tin đăng nhập và mật khẩu cho cả các dịch vụ do Google Workspace lưu trữ cũng như các dịch vụ khác mà bạn có thể đang lưu trữ trong tổ chức của mình. Cụ thể là khi sử dụng SSO, một ứng dụng web được lưu trữ (chẳng hạn như Google Workspace) sẽ chuyển hướng người dùng đến nhà cung cấp danh tính của tổ chức để xác thực người dùng khi họ đăng nhập. Để biết thông tin chi tiết, hãy xem bài viết Tìm hiểu về tính năng SSO dựa trên SAML cho Google Workspace.
Việc định cấu hình SSO bao gồm việc nhập thông tin cần thiết để dịch vụ Google Workspace giao tiếp với nhà cung cấp danh tính lưu trữ thông tin đăng nhập của người dùng, cũng như thiết lập các đường liên kết mà người dùng sẽ được gửi đến để đăng nhập, đăng xuất và thay đổi mật khẩu. API Cài đặt dành cho quản trị viên cho phép bạn cập nhật và truy xuất các chế độ cài đặt này theo phương thức lập trình. Google sử dụng khoá công khai mà bạn đã tạo để xác minh yêu cầu SSO này với nhà cung cấp danh tính của bạn và đảm bảo rằng phản hồi SAML của khoá riêng tư không bị sửa đổi trong quá trình truyền qua mạng.
Để biết tóm tắt ngắn gọn về API cụ thể khi sử dụng chế độ cài đặt SSO, hãy lấy chứng chỉ khoá công khai từ nhà cung cấp danh tính, đăng ký khoá công khai với Google và thiết lập chế độ cài đặt truy vấn SSO dựa trên SAML. Để biết thông báo lỗi, hãy xem bài viết Khắc phục sự cố về SSO:
- Tạo khoá – Với nhà cung cấp danh tính, hãy tạo một nhóm khoá công khai và khoá riêng tư bằng cách sử dụng thuật toán DSA hoặc RSA. Khoá công khai nằm trong chứng chỉ có định dạng X.509. Để biết thêm thông tin về các khoá ký Đăng nhập một lần dựa trên SAML, hãy xem bài viết Tạo khoá và chứng chỉ cho dịch vụ Đăng nhập một lần của Google Workspace.
- Đăng ký với Google – Sử dụng chế độ cài đặt Đăng nhập một lần của API Cài đặt dành cho quản trị viên để đăng ký chứng chỉ khoá công khai với Google.
- Thiết lập chế độ cài đặt SSO – Sử dụng chế độ cài đặt Đăng nhập một lần của API Cài đặt dành cho quản trị viên để định cấu hình các chế độ cài đặt dùng để giao tiếp với máy chủ của nhà cung cấp danh tính của miền.
- Chế độ cài đặt cổng
Nguồn cấp dữ liệu này cho phép quản trị viên miền kiểm soát việc định tuyến email cho miền của họ.
Các thao tác định tuyến email cho phép quản trị viên chỉ định chế độ cài đặt định tuyến email ở cấp miền. Chế độ này tương tự như chức năng định tuyến email trong phần cài đặt Gmail của Bảng điều khiển dành cho quản trị viên. Để biết thêm thông tin, hãy xem bài viết Định tuyến email và cấu hình phân phối kép của tính năng định tuyến email.
Ví dụ về yêu cầu và phản hồi XML của API Cài đặt dành cho quản trị viên
Tài liệu này cung cấp các ví dụ về mã cho các yêu cầu và phản hồi cơ bản của API Cài đặt dành cho quản trị viên bằng XML và HTTP thô. Ví dụ về ngôn ngữ mặc định của miền này cho thấy cú pháp XML và HTTP đầy đủ cho nội dung của mục nhập yêu cầu và phản hồi, thường có trong mỗi thao tác:
Để thay đổi chế độ cài đặt cổng email gửi đi của miền, hãy gửi yêu cầu HTTP PUT đến URL nguồn cấp dữ liệu cổng:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
XML entry AtomPub của yêu cầu PUT về ngôn ngữ mặc định của miền là:
<atom:entry xmlns:atom='http://www.w3.org/2005/Atom'
xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>
Ngoại trừ các thuộc tính và giá trị dành riêng cho thao tác, các phần tử atom:property đại diện cho một cặp khoá-giá trị chứa thông tin về một thuộc tính mà bạn muốn truy xuất hoặc cập nhật. Các thuộc tính này thường có trong tất cả nội dung yêu cầu của API Cài đặt dành cho quản trị viên.
Phần tử entry của phản hồi về ngôn ngữ mặc định của miền sẽ trả về các thuộc tính smartHost và smtpMode cùng với cú pháp XML thường có trong tất cả nội dung phản hồi của API Cài đặt dành cho quản trị viên:
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<id>https://apps-apis.google.com/a/feeds/domain/2.0/domainName/email/gateway</id>
<updated>2008-12-17T23:59:23.887Z</updated>
<link rel='self' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
2.0/domainName/email/gateway'/>
<link rel='edit' type='application/atom+xml' href='https://apps-apis.google.com/a/feeds/domain/
2.0/domainName/email/gateway'/>
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</entry>
Quản lý chế độ cài đặt Đăng nhập một lần
Tính năng Đăng nhập một lần (SSO) của Google Workspace cho phép người dùng đăng nhập vào nhiều dịch vụ mà chỉ cần nhập thông tin đăng nhập và mật khẩu một lần. Mật khẩu này được nhà cung cấp danh tính của miền lưu trữ, chứ không phải Google Workspace. Để biết thêm thông tin, hãy xem trang SSO của Trung tâm trợ giúp. Các phần sau đây minh hoạ định dạng XML được dùng cho chế độ cài đặt Đăng nhập một lần.
Truy xuất chế độ cài đặt Đăng nhập một lần
Để truy xuất chế độ cài đặt Đăng nhập một lần, hãy gửi yêu cầu HTTP GET đến URL nguồn cấp dữ liệu chung của SSO và thêm tiêu đề Authorization như mô tả trong bài viết Xác thực với dịch vụ Cài đặt dành cho quản trị viên. Để biết thông báo lỗi, hãy xem bài viết Khắc phục sự cố về SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Thao tác này không có tham số nào trong nội dung yêu cầu.
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 OK cùng với nguồn cấp dữ liệu AtomPub có chế độ cài đặt SSO của miền.
XML phản hồi GET sẽ trả về các thuộc tính samlSignonUri, samlLogoutUri, changePasswordUri, enableSSO, ssoWhitelist và useDomainSpecificIssuer:
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
...
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='true'/>
<apps:property name='ssoWhitelist' value='CIDR formatted IP address'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>
Các thuộc tính bao gồm:
- samlSignonUri
- URL của nhà cung cấp danh tính mà Google Workspace gửi yêu cầu SAML để xác thực người dùng.
- samlLogoutUri
- Địa chỉ mà người dùng sẽ được gửi đến khi đăng xuất khỏi ứng dụng web.
- changePasswordUri
- Địa chỉ mà người dùng sẽ được gửi đến khi muốn thay đổi mật khẩu SSO cho ứng dụng web.
- enableSSO
- Bật tính năng SSO dựa trên SAML cho miền này. Nếu trước đây bạn đã định cấu hình chế độ cài đặt SSO và sau đó đặt
enableSSOthànhenableSSO=false, thì các chế độ cài đặt mà bạn đã nhập trước đó vẫn được lưu. - ssoWhitelist
- ssoWhitelist là địa chỉ IP mặt nạ mạng ở định dạng Định tuyến liên miền không phân lớp (CIDR). ssoWhitelist xác định những người dùng đăng nhập bằng SSO và những người dùng đăng nhập bằng trang xác thực tài khoản Google Workspace. Nếu không chỉ định mặt nạ nào, tất cả người dùng sẽ đăng nhập bằng SSO. Để biết thêm thông tin, hãy xem bài viết Cách hoạt động của mặt nạ mạng.
- useDomainSpecificIssuer
- Bạn có thể sử dụng tổ chức phát hành dành riêng cho miền trong yêu cầu SAML gửi đến nhà cung cấp danh tính. Mặc dù không cần thiết đối với hầu hết các trường hợp triển khai SSO, nhưng tính năng này rất hữu ích trong các công ty lớn sử dụng một nhà cung cấp danh tính duy nhất để xác thực toàn bộ tổ chức có nhiều miền phụ. Việc cung cấp nhà cung cấp miền cụ thể sẽ xác định miền phụ nào cần liên kết với yêu cầu. Để biết thêm thông tin, hãy xem Phần tử Nhà cung cấp trong yêu cầu SAML hoạt động như thế nào?
Nếu yêu cầu của bạn không thành công vì lý do nào đó, thì hệ thống sẽ trả về một mã trạng thái khác. Để biết thêm thông tin về mã trạng thái Google Data API, hãy xem Mã trạng thái HTTP.
Cập nhật chế độ cài đặt Đăng nhập một lần
Để cập nhật chế độ cài đặt SSO của miền, trước tiên, hãy truy xuất chế độ cài đặt SSO bằng thao tác
Truy xuất chế độ cài đặt Đăng nhập một lần,
sửa đổi chế độ cài đặt đó, rồi gửi yêu cầu PUT đến URL nguồn cấp dữ liệu SSO. Hãy đảm bảo <id>
giá trị trong mục nhập đã cập nhật của bạn khớp chính xác với <id> của mục nhập hiện có.
Thêm tiêu đề Authorization như mô tả trong Xác thực với dịch vụ
API Cài đặt dành cho quản trị viên. Để biết thông báo lỗi,
hãy xem bài viết Khắc phục sự cố về SSO.
Khi cập nhật chế độ cài đặt Đăng nhập một lần, hãy gửi yêu cầu HTTP PUT đến URL nguồn cấp dữ liệu chung của SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/general
Nội dung XML của yêu cầu PUT là:
<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
<apps:property name='enableSSO' value='false' />
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon' />
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout' />
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword' />
<apps:property name='ssoWhitelist' value='127.0.0.1/32' />
<apps:property name='useDomainSpecificIssuer' value='false'/>
</atom:entry>
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 OK cùng với nguồn cấp dữ liệu AtomPub có chế độ cài đặt SSO.
XML phản hồi PUT là:
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='samlSignonUri' value='http://www.example.com/sso/signon'/>
<apps:property name='samlLogoutUri' value='http://www.example.com/sso/logout'/>
<apps:property name='changePasswordUri' value='http://www.example.com/sso/changepassword'/>
<apps:property name='enableSSO' value='false'/>
<apps:property name='ssoWhitelist' value='127.0.0.1/32'/>
<apps:property name='useDomainSpecificIssuer' value='false'/>
</entry>
Nếu yêu cầu của bạn không thành công vì lý do nào đó, thì hệ thống sẽ trả về một mã trạng thái khác. Để biết thêm thông tin về mã trạng thái Google Data API, hãy xem Mã trạng thái HTTP.
Bạn không được thay đổi chế độ cài đặt Đăng nhập một lần khi khách hàng mục tiêu đã
bật tính năng Phê duyệt nhiều bên cho các hành động nhạy cảm. Yêu cầu sẽ không thành công với
errorCode="1811" và
reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".
Truy xuất khoá ký Đăng nhập một lần
Để truy xuất khoá ký Đăng nhập một lần, hãy gửi yêu cầu HTTP GET đến URL nguồn cấp dữ liệu khoá ký SSO
và thêm tiêu đề Authorization như mô tả trong
bài viết Xác thực với dịch vụ Cài đặt dành cho quản trị viên. Để biết thông báo lỗi,
hãy xem Khắc phục sự cố về SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
Thao tác này không có tham số nào trong nội dung yêu cầu.
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 OK cùng với nguồn cấp dữ liệu AtomPub có khoá ký.
XML phản hồi GET sẽ trả về thuộc tính signingKey:
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</entry>
Nếu yêu cầu của bạn không thành công vì lý do nào đó, thì hệ thống sẽ trả về một mã trạng thái khác. Để biết thêm thông tin về mã trạng thái Google Data API, hãy xem Mã trạng thái HTTP.
Cập nhật khoá ký Đăng nhập một lần
Để cập nhật khoá ký SSO của miền, trước tiên, hãy truy xuất khoá ký bằng thao tác
Truy xuất khoá ký Đăng nhập một lần
, sửa đổi khoá ký đó, rồi gửi yêu cầu PUT đến
URL nguồn cấp dữ liệu khoá ký SSO. Hãy đảm bảo giá trị <id> trong mục nhập đã cập nhật của bạn khớp chính xác với
<id> của mục nhập hiện có. Để biết thêm thông tin về các khoá ký Đăng nhập một lần dựa trên SAML, hãy xem bài viết Tạo khoá và chứng chỉ cho dịch vụ Đăng nhập một lần của Google Workspace.
Khi cập nhật khoá ký Đăng nhập một lần, hãy gửi yêu cầu HTTP PUT đến URL nguồn cấp dữ liệu khoá ký SSO:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/sso/signingkey
XML yêu cầu PUT là:
<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='signingKey' value='yourBase64EncodedPublicKey'/>
</atom:entry>
Bạn không được thay đổi chế độ cài đặt Đăng nhập một lần khi khách hàng mục tiêu đã
bật tính năng Phê duyệt nhiều bên cho các hành động nhạy cảm. Yêu cầu sẽ không thành công với
errorCode="1811" và
reason="LegacyInboundSsoChangeNotAllowedWithMultiPartyApproval".
Quản lý cổng email
Phần cổng email gửi đi cho biết cách API Cài đặt dành cho quản trị viên hỗ trợ việc định tuyến email gửi đi từ người dùng trong miền của bạn.
Truy xuất chế độ cài đặt cổng email gửi đi
Để truy xuất chế độ cài đặt cổng email gửi đi, hãy gửi yêu cầu HTTP GET đến URL nguồn cấp dữ liệu cổng
và thêm tiêu đề Authorization như mô tả trong bài viết Xác thực
với dịch vụ Cài đặt dành cho quản trị viên:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
Thao tác này không có tham số nào trong nội dung yêu cầu.
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 OK cùng với nguồn cấp dữ liệu AtomPub có thông tin trạng thái cổng email.
Phản hồi GET sẽ trả về các thuộc tính smartHost và smtpMode. Để biết thêm
thông tin về các thuộc tính này, hãy xem bài viết Cập nhật chế độ cài đặt cổng email gửi đi.
Ví dụ về một phản hồi có thể có là:
<?xml version='1.0' encoding='UTF-8'?>
<entry xmlns='http://www.w3.org/2005/Atom' xmlns:apps='http://schemas.google.com/apps/2006'>
...
<apps:property name='smartHost' value='smtpout.domain.com'/>
<apps:property name='smtpMode' value='SMTP'/>
</entry>
Nếu yêu cầu của bạn không thành công vì lý do nào đó, thì hệ thống sẽ trả về một mã trạng thái khác. Để biết thêm thông tin về mã trạng thái Google Data API, hãy xem Mã trạng thái HTTP.
Cập nhật chế độ cài đặt cổng email gửi đi
Để cập nhật chế độ cài đặt cổng email gửi đi của miền, hãy gửi yêu cầu HTTP PUT đến URL nguồn cấp dữ liệu cổng:
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/email/gateway
XML yêu cầu PUT là:
<atom:entry xmlns:atom='http://www.w3.org/2005/Atom' xmlns:apps="http://schemas.google.com/apps/2006">
<apps:property name='smartHost' value='smtp.out.domain.com' />
<apps:property name='smtpMode' value='SMTP' />
</atom:entry>
Các thuộc tính của yêu cầu là:
- smartHost
- Địa chỉ IP hoặc tên máy chủ của máy chủ SMTP. Google Workspace định tuyến email gửi đi đến máy chủ này.
- smtpMode
- Giá trị mặc định là SMTP. Một giá trị khác là SMTP_TLS, giúp bảo mật kết nối bằng TLS khi gửi thư.
Phản hồi thành công sẽ trả về mã trạng thái HTTP 200 OK cùng với nguồn cấp dữ liệu AtomPub có trạng thái chế độ cài đặt cổng email.
Nếu yêu cầu của bạn không thành công vì lý do nào đó, thì hệ thống sẽ trả về một mã trạng thái khác. Để biết thêm thông tin về mã trạng thái Google Data API, hãy xem Mã trạng thái HTTP.
Các điểm cuối ngừng hoạt động vào ngày 31 tháng 10 năm 2018
Chúng tôi đã ngừng cung cấp các điểm cuối sau đây trong thông báo này. Các điểm cuối này đã ngừng hoạt động vào ngày 31 tháng 10 năm 2018 và không còn được cung cấp nữa.
https://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/defaultLanguagehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/organizationNamehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/currentNumberOfUsershttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/general/maximumNumberOfUsershttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/supportPINhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/customerPINhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/adminSecondaryEmailhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/editionhttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/creationTimehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/accountInformation/countryCodehttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/appearance/customLogohttps://apps-apis.google.com/a/feeds/domain/2.0/{domainName}/verification/mx