介绍
# Google Workspace Admin
通过托管的 OAuth 身份验证访问 Google Workspace Admin SDK。管理 Google Workspace 的用户、群组、组织单元、角色和域名设置。
## 快速开始
```bash # List users in the domain python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer&maxResults=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## Base URL
``` https://gateway.maton.ai/google-workspace-admin/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Admin SDK API 端点路径。网关将请求代理到 `admin.googleapis.com` 并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization header 中包含 Maton API key：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API key 设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API Key
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API key
## 连接管理
在 `https://ctrl.maton.ai` 管理您的 Google OAuth 连接。
### 列出连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-workspace-admin&status=ACTIVE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 创建连接
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-workspace-admin'}).encode() req = urllib.request.Request('https://ctrl.maton.ai/connections', data=data, method='POST') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Content-Type', 'application/json') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 获取连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "connection": { "connection_id": "21fd90f9-5935-43cd-b6c8-bde9d915ca80", "status": "ACTIVE", "creation_time": "2025-12-08T07:20:53.488460Z", "last_updated_time": "2026-01-31T20:03:32.593153Z", "url": "https://connect.maton.ai/?session_token=...", "app": "google-workspace-admin", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### 删除连接
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections/{connection_id}', method='DELETE') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 指定连接
如果您有多个 Google Workspace Admin 连接，请使用 `Maton-Connection` header 指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') req.add_header('Maton-Connection', '21fd90f9-5935-43cd-b6c8-bde9d915ca80') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
如果省略，网关将使用默认（最旧的）活动连接。
## API 参考
### 用户
#### 列出用户
```bash GET /google-workspace-admin/admin/directory/v1/users?customer=my_customer&maxResults=100 ```
查询参数： - `customer` - 客户 ID，或您域名的 `my_customer`（必需） - `domain` - 按特定域名筛选 - `maxResults` - 每页最大结果数（1-500，默认 100） - `orderBy` - 按 `email`、`familyName` 或 `givenName` 排序 - `query` - 搜索查询（例如 `email:john*`、`name:John*`） - `pageToken` - 分页令牌
**示例：**
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer&query=email:john*') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
**响应：** ```json { "kind": "admin#directory#users", "users": [ { "id": "123456789", "primaryEmail": "[email protected]", "name": { "givenName": "John", "familyName": "Doe", "fullName": "John Doe" }, "isAdmin": false, "isDelegatedAdmin": false, "suspended": false, "creationTime": "2024-01-15T10:30:00.000Z", "lastLoginTime": "2025-02-01T08:00:00.000Z", "orgUnitPath": "/Sales" } ], "nextPageToken": "..." } ```
#### 获取用户
```bash GET /google-workspace-admin/admin/directory/v1/users/{userKey} ```
`userKey` 可以是用户的主邮箱或唯一用户 ID。
#### 创建用户
```bash POST /google-workspace-admin/admin/directory/v1/users Content-Type: application/json
{ "primaryEmail": "[email protected]", "name": { "givenName": "Jane", "familyName": "Smith" }, "password": "temporaryPassword123!", "changePasswordAtNextLogin": true, "orgUnitPath": "/Engineering" } ```
#### 更新用户
```bash PUT /google-workspace-admin/admin/directory/v1/users/{userKey} Content-Type: application/json
{ "name": { "givenName": "Jane", "familyName": "Smith-Johnson" }, "suspended": false, "orgUnitPath": "/Sales" } ```
#### 部分更新用户
```bash PATCH /google-workspace-admin/admin/directory/v1/users/{userKey} Content-Type: application/json
{ "suspended": true } ```
#### 删除用户
```bash DELETE /google-workspace-admin/admin/directory/v1/users/{userKey} ```
#### 设为管理员
```bash POST /google-workspace-admin/admin/directory/v1/users/{userKey}/makeAdmin Content-Type: application/json
{ "status": true } ```
### 群组
#### 列出群组
```bash GET /google-workspace-admin/admin/directory/v1/groups?customer=my_customer ```
查询参数： - `customer` - 客户 ID 或 `my_customer`（必需） - `domain` - 按域名筛选 - `maxResults` - 最大结果数（1-200） - `userKey` - 列出特定用户的群组
#### 获取群组
```bash GET /google-workspace-admin/admin/directory/v1/groups/{groupKey} ```
`groupKey` 可以是群组的邮箱或唯一 ID。
#### 创建群组
```bash POST /google-workspace-admin/admin/directory/v1/groups Content-Type: application/json
{ "email": "[email protected]", "name": "Engineering Team", "description": "All engineering staff" } ```
#### 更新群组
```bash PUT /google-workspace-admin/admin/directory/v1/groups/{groupKey} Content-Type: application/json
{ "name": "Engineering Department", "description": "Updated description" } ```
#### 删除群组
```bash DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey} ```
### 群组成员
#### 列出成员
```bash GET /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members ```
#### 添加成员
```bash POST /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members Content-Type: application/json
{ "email": "[email protected]", "role": "MEMBER" } ```
角色：`OWNER`、`MANAGER`、`MEMBER`
#### 更新成员角色
```bash PATCH /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey} Content-Type: application/json
{ "role": "MANAGER" } ```
#### 移除成员
```bash DELETE /google-workspace-admin/admin/directory/v1/groups/{groupKey}/members/{memberKey} ```
### 组织单元
#### 列出组织单元
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits ```
查询参数： - `type` - `all`（默认）或 `children` - `orgUnitPath` - 父组织单元路径
#### 获取组织单元
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} ```
#### 创建组织单元
```bash POST /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits Content-Type: application/json
{ "name": "Engineering", "parentOrgUnitPath": "/", "description": "Engineering department" } ```
#### 更新组织单元
```bash PUT /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} Content-Type: application/json
{ "description": "Updated description" } ```
#### 删除组织单元
```bash DELETE /google-workspace-admin/admin/directory/v1/customer/my_customer/orgunits/{orgUnitPath} ```
### 域名
#### 列出域名
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains ```
#### 获取域名
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/domains/{domainName} ```
### 角色
#### 列出角色
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roles ```
#### 列出角色分配
```bash GET /google-workspace-admin/admin/directory/v1/customer/my_customer/roleassignments ```
查询参数： - `userKey` - 按用户筛选 - `roleId` - 按角色筛选
#### 创建角色分配
```bash POST /google-workspace-admin/admin/directory/v1/customer/my_customer/roleassignments Content-Type: application/json
{ "roleId": "123456789", "assignedTo": "user_id", "scopeType": "CUSTOMER" } ```
## 代码示例
### JavaScript
```javascript const headers = { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` };
// List users const users = await fetch( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer', { headers } ).then(r => r.json());
// Create user await fetch( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', { method: 'POST', headers: { ...headers, 'Content-Type': 'application/json' }, body: JSON.stringify({ primaryEmail: '[email protected]', name: { givenName: 'New', familyName: 'User' }, password: 'TempPass123!', changePasswordAtNextLogin: true }) } ); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}
# List users users = requests.get( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', headers=headers, params={'customer': 'my_customer'} ).json()
# Create user response = requests.post( 'https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users', headers=headers, json={ 'primaryEmail': '[email protected]', 'name': {'givenName': 'New', 'familyName': 'User'}, 'password': 'TempPass123!', 'changePasswordAtNextLogin': True } ) ```
## 注意事项
- 将 `my_customer` 用作您自己域名的客户 ID - User key 可以是主邮箱或唯一用户 ID - Group key 可以是群组邮箱或唯一群组 ID - 组织单元路径以 `/` 开头（例如 `/Engineering/Frontend`） - 大多数操作需要管理员权限 - 密码必须符合 Google 的复杂性要求 - 重要：使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，像 `$MATON_API_KEY` 这样的环境变量可能无法正确展开。通过管道传递时您可能会遇到“Invalid API key”错误。
## 错误处理
| Status | 含义 | |--------|---------| | 400 | 缺少 Google Workspace Admin 连接 | | 401 | 无效或缺少 Maton API key | | 403 | 管理员权限不足 | | 404 | 未找到用户、群组或资源 | | 429 | 速率受限（每个账户每秒 10 次请求）| | 4xx/5xx | 来自 Admin SDK API 的透传错误 |
### 故障排除：API Key 问题
1. 检查是否已设置 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API key 是否有效：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
### 故障排除：无效的应用名称
1. 确保您的 URL 路径以 `google-workspace-admin` 开头。例如：
- 正确：`https://gateway.maton.ai/google-workspace-admin/admin/directory/v1/users?customer=my_customer` - 错误：`https://gateway.maton.ai/admin/directory/v1/users?customer=my_customer`
## 资源
- [Admin SDK 概览](https://developers.google.com/admin-sdk) - [Directory API 用户](https://developers.google.com/admin-sdk/directory/reference/rest/v1/users) - [Directory API 群组](https://developers.google.com/admin-sdk/directory/reference/rest/v1/groups) - [Directory API 成员](https://developers.google.com/admin-sdk/directory/reference/rest/v1/members) - [Directory API 组织单元](https://developers.google.com/admin-sdk/directory/reference/rest/v1/orgunits) - [Directory API 域名](https://developers.google.com/admin-sdk/directory/reference/rest/v1/domains) - [Directory API 角色](https://developers.google.com/admin-sdk/directory/reference/rest/v1/roles) - [Admin SDK 指南](https://developers.google.com/admin-sdk/directory/v1/guides) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])