介绍
# Google Contacts
通过托管的 OAuth 身份验证访问 Google People API。管理联系人、联系人组并搜索您的通讯录。
## 快速开始
```bash # List contacts python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=10') req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}') print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2)) EOF ```
## 基础 URL
``` https://gateway.maton.ai/google-contacts/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Google People API 端点路径。网关将请求代理到 `people.googleapis.com`，并自动注入您的 OAuth 令牌。
## 身份验证
所有请求都需要在 Authorization 标头中包含 Maton API 密钥：
``` Authorization: Bearer $MATON_API_KEY ```
**环境变量：** 将您的 API 密钥设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### 获取您的 API 密钥
1. 在 [maton.ai](https://maton.ai) 登录或创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API 密钥
## 连接管理
在 `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-contacts&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-contacts'}).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-contacts", "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 联系人连接，请使用 `Maton-Connection` 标头指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names&pageSize=10') 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-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=100 ```
**查询参数：** - `personFields`（必需）：要返回的以逗号分隔的字段列表（参见“联系人字段”部分） - `pageSize`：要返回的联系人数量（最多 1000，默认 100） - `pageToken`：用于分页的令牌 - `sortOrder`：`LAST_MODIFIED_ASCENDING`、`LAST_MODIFIED_DESCENDING`、`FIRST_NAME_ASCENDING` 或 `LAST_NAME_ASCENDING`
**响应：** ```json { "connections": [ { "resourceName": "people/c1234567890", "names": [{"displayName": "John Doe", "givenName": "John", "familyName": "Doe"}], "emailAddresses": [{"value": "[email protected]"}], "phoneNumbers": [{"value": "+1-555-0123"}] } ], "totalPeople": 1, "totalItems": 1, "nextPageToken": "..." } ```
#### 获取联系人
```bash GET /google-contacts/v1/people/{resourceName}?personFields=names,emailAddresses,phoneNumbers ```
使用来自列表或创建操作的资源名称（例如 `people/c1234567890`）。
#### 创建联系人
```bash POST /google-contacts/v1/people:createContact Content-Type: application/json
{ "names": [{"givenName": "John", "familyName": "Doe"}], "emailAddresses": [{"value": "[email protected]"}], "phoneNumbers": [{"value": "+1-555-0123"}], "organizations": [{"name": "Acme Corp", "title": "Engineer"}] } ```
#### 更新联系人
```bash PATCH /google-contacts/v1/people/{resourceName}:updateContact?updatePersonFields=names,emailAddresses Content-Type: application/json
{ "etag": "%EgcBAgkLLjc9...", "names": [{"givenName": "John", "familyName": "Smith"}], "emailAddresses": [{"value": "[email protected]"}] } ```
**注意：** 包含来自获取/列表响应的 `etag`，以确保您正在更新最新版本。
#### 删除联系人
```bash DELETE /google-contacts/v1/people/{resourceName}:deleteContact ```
#### 批量获取联系人
```bash GET /google-contacts/v1/people:batchGet?resourceNames=people/c123&resourceNames=people/c456&personFields=names,emailAddresses ```
#### 批量创建联系人
```bash POST /google-contacts/v1/people:batchCreateContacts Content-Type: application/json
{ "contacts": [ { "contactPerson": { "names": [{"givenName": "Alice", "familyName": "Smith"}], "emailAddresses": [{"value": "[email protected]"}] } }, { "contactPerson": { "names": [{"givenName": "Bob", "familyName": "Jones"}], "emailAddresses": [{"value": "[email protected]"}] } } ], "readMask": "names,emailAddresses" } ```
#### 批量删除联系人
```bash POST /google-contacts/v1/people:batchDeleteContacts Content-Type: application/json
{ "resourceNames": ["people/c123", "people/c456"] } ```
#### 搜索联系人
```bash GET /google-contacts/v1/people:searchContacts?query=John&readMask=names,emailAddresses ```
**注意：** 由于索引原因，新创建的联系人的搜索结果可能会有轻微延迟。
### 联系人组操作
#### 列出联系人组
```bash GET /google-contacts/v1/contactGroups?pageSize=100 ```
**响应：** ```json { "contactGroups": [ { "resourceName": "contactGroups/starred", "groupType": "SYSTEM_CONTACT_GROUP", "name": "starred", "formattedName": "Starred" }, { "resourceName": "contactGroups/abc123", "groupType": "USER_CONTACT_GROUP", "name": "Work", "formattedName": "Work", "memberCount": 5 } ], "totalItems": 2 } ```
#### 获取联系人组
```bash GET /google-contacts/v1/contactGroups/{resourceName}?maxMembers=100 ```
对于系统组，使用 `contactGroups/starred`、`contactGroups/family` 等，对于用户组使用资源名称。
#### 创建联系人组
```bash POST /google-contacts/v1/contactGroups Content-Type: application/json
{ "contactGroup": { "name": "Work Contacts" } } ```
#### 删除联系人组
```bash DELETE /google-contacts/v1/contactGroups/{resourceName}?deleteContacts=false ```
设置 `deleteContacts=true` 以同时删除组中的联系人。
#### 批量获取联系人组
```bash GET /google-contacts/v1/contactGroups:batchGet?resourceNames=contactGroups/starred&resourceNames=contactGroups/family ```
#### 修改组成员
从组中添加或移除联系人：
```bash POST /google-contacts/v1/contactGroups/{resourceName}/members:modify Content-Type: application/json
{ "resourceNamesToAdd": ["people/c123", "people/c456"], "resourceNamesToRemove": ["people/c789"] } ```
### 其他联系人
其他联系人是您曾与之互动（例如通过电子邮件）但未明确添加到您联系人列表的人员。
#### 列出其他联系人
```bash GET /google-contacts/v1/otherContacts?readMask=names,emailAddresses&pageSize=100 ```
#### 将其他联系人复制到“我的联系人”
```bash POST /google-contacts/v1/{resourceName}:copyOtherContactToMyContactsGroup Content-Type: application/json
{ "copyMask": "names,emailAddresses,phoneNumbers" } ```
## 联系人字段
将这些字段与 `personFields` 或 `readMask` 参数一起使用：
| 字段 | 描述 | |-------|-------------| | `names` | 显示名称、名字、姓氏 | | `emailAddresses` | 带有类型的电子邮件地址 | | `phoneNumbers` | 带有类型的电话号码 | | `addresses` | 邮政地址 | | `organizations` | 公司、职位、部门 | | `biographies` | 关于该人员的简介/备注 | | `birthdays` | 生日信息 | | `urls` | 网站 URL | | `photos` | 个人资料照片 | | `memberships` | 联系人组成员身份 | | `metadata` | 来源和更新信息 |
多个字段：`personFields=names,emailAddresses,phoneNumbers,organizations`
## 分页
使用 `pageSize` 和 `pageToken` 进行分页：
```bash GET /google-contacts/v1/people/me/connections?personFields=names&pageSize=100&pageToken=NEXT_PAGE_TOKEN ```
响应包含分页信息：
```json { "connections": [...], "totalPeople": 500, "nextPageToken": "...", "nextSyncToken": "..." } ```
使用 `pageToken` 继续获取，直到不再返回 `nextPageToken`。
## 代码示例
### JavaScript
```javascript const response = await fetch( 'https://gateway.maton.ai/google-contacts/v1/people/me/connections?personFields=names,emailAddresses&pageSize=50', { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } ); const data = await response.json(); ```
### Python
```python import os import requests
response = requests.get( 'https://gateway.maton.ai/google-contacts/v1/people/me/connections', headers={'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'}, params={ 'personFields': 'names,emailAddresses,phoneNumbers', 'pageSize': 50 } ) data = response.json() ```
## 注意事项
- 联系人的资源名称遵循模式 `people/c{id}`（例如 `people/c1234567890`） - 联系人组的资源名称遵循模式 `contactGroups/{id}`（例如 `contactGroups/abc123`） - 系统联系人组包括：`starred`、`friends`、`family`、`coworkers`、`myContacts`、`all`、`blocked` - 大多数读取操作都需要 `personFields` 参数 - 更新联系人时，包含 `etag` 以防止覆盖并发更改 - 针对同一用户的变更请求应顺序发送，以避免增加延迟和失败 - 重要：使用 curl 命令时，如果 URL 包含括号，请使用 `curl -g` 以禁用 glob 解析 - 重要：将 curl 输出通过管道传递给 `jq` 或其他命令时，在某些 shell 环境中，`$MATON_API_KEY` 等环境变量可能无法正确展开
## 错误处理
| 状态 | 含义 | |--------|---------| | 400 | 缺少 Google 联系人连接或请求无效 | | 401 | Maton API 密钥无效或缺失 | | 403 | 权限被拒绝（检查 OAuth 范围） | | 404 | 联系人或组未找到 | | 429 | 速率受限 | | 4xx/5xx | 来自 Google People API 的透传错误 |
### 故障排除：API 密钥问题
1. 检查是否设置了 `MATON_API_KEY` 环境变量：
```bash echo $MATON_API_KEY ```
2. 通过列出连接来验证 API 密钥是否有效：
```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-contacts` 开头。例如：
- 正确：`https://gateway.maton.ai/google-contacts/v1/people/me/connections` - 错误：`https://gateway.maton.ai/v1/people/me/connections`
## 资源
- [Google People API 概览](https://developers.google.com/people/api/rest) - [People 资源](https://developers.google.com/people/api/rest/v1/people) - [联系人组资源](https://developers.google.com/people/api/rest/v1/contactGroups) - [联系人字段参考](https://developers.google.com/people/api/rest/v1/people#Person) - [Maton 社区](https://discord.com/invite/dBfFAcefs2) - [Maton 支持](mailto:[email protected])