Google 通讯录

通过托管的 OAuth 认证访问 Google People API。管理联系人、联系人群组并搜索您的通讯录。

快速入门

# 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：

export MATON_API_KEY="YOUR_API_KEY"

获取您的 API 密钥

1. 登录或在maton.ai
2. 创建账户转到
3. maton.ai/settings

复制您的 API 密钥

在以下网址管理您的Google联系人OAuth连接https://ctrl.maton.ai.

列出连接

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

创建连接

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

获取连接

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

响应：

{
  "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": {}
  }
}

在浏览器中打开返回的网址以完成OAuth授权。

删除连接

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标头指定要使用哪一个：

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参考

联系人操作

列出联系人

GET /google-contacts/v1/people/me/connections?personFields=names,emailAddresses,phoneNumbers&pageSize=100

查询参数：

• personFields（必需）：要返回的字段的逗号分隔列表（参见“人员字段”部分）。
• 每页大小：返回的联系人数量（最多1000条，默认100条）
• 页面令牌：用于分页的令牌
• 排序顺序：最后修改时间升序、最后修改时间降序、名字升序或姓氏升序

响应：

{
  "connections": [
    {
      "resourceName": "people/c1234567890",
      "names": [{"displayName": "John Doe", "givenName": "John", "familyName": "Doe"}],
      "emailAddresses": [{"value": "john@example.com"}],
      "phoneNumbers": [{"value": "+1-555-0123"}]
    }
  ],
  "totalPeople": 1,
  "totalItems": 1,
  "nextPageToken": "..."
}

获取联系人

GET /google-contacts/v1/people/{resourceName}?personFields=names,emailAddresses,phoneNumbers

使用来自列表或创建操作的资源名称（例如，people/c1234567890）。

创建联系人

POST /google-contacts/v1/people:createContact
Content-Type: application/json

{
  "names": [{"givenName": "John", "familyName": "Doe"}],
  "emailAddresses": [{"value": "john@example.com"}],
  "phoneNumbers": [{"value": "+1-555-0123"}],
  "organizations": [{"name": "Acme Corp", "title": "Engineer"}]
}

更新联系人

PATCH /google-contacts/v1/people/{resourceName}:updateContact?updatePersonFields=names,emailAddresses
Content-Type: application/json

{
  "etag": "%EgcBAgkLLjc9...",
  "names": [{"givenName": "John", "familyName": "Smith"}],
  "emailAddresses": [{"value": "john.smith@example.com"}]
}

注意：请包含etag从获取/列表响应中，以确保您正在更新最新版本。

删除联系人

DELETE /google-contacts/v1/people/{resourceName}:deleteContact

批量获取联系人

GET /google-contacts/v1/people:batchGet?resourceNames=people/c123&resourceNames=people/c456&personFields=names,emailAddresses

批量创建联系人

POST /google-contacts/v1/people:batchCreateContacts
Content-Type: application/json

{
  "contacts": [
    {
      "contactPerson": {
        "names": [{"givenName": "Alice", "familyName": "Smith"}],
        "emailAddresses": [{"value": "alice@example.com"}]
      }
    },
    {
      "contactPerson": {
        "names": [{"givenName": "Bob", "familyName": "Jones"}],
        "emailAddresses": [{"value": "bob@example.com"}]
      }
    }
  ],
  "readMask": "names,emailAddresses"
}

批量删除联系人

POST /google-contacts/v1/people:batchDeleteContacts
Content-Type: application/json

{
  "resourceNames": ["people/c123", "people/c456"]
}

搜索联系人

GET /google-contacts/v1/people:searchContacts?query=John&readMask=names,emailAddresses

注意：由于索引原因，新创建的联系人在搜索结果中可能会有轻微延迟。

联系人组操作

列出联系人组

GET /google-contacts/v1/contactGroups?pageSize=100

响应：

{
  "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
}

获取联系人组

GET /google-contacts/v1/contactGroups/{resourceName}?maxMembers=100

使用contactGroups/starred、contactGroups/family等表示系统组，或使用用户组的资源名称。

创建联系人组

POST /google-contacts/v1/contactGroups
Content-Type: application/json

{
  "contactGroup": {
    "name": "Work Contacts"
  }
}

删除联系人组

DELETE /google-contacts/v1/contactGroups/{resourceName}?deleteContacts=false

设置deleteContacts=true以同时删除组内的联系人。

批量获取联系人组

GET /google-contacts/v1/contactGroups:batchGet?resourceNames=contactGroups/starred&resourceNames=contactGroups/family

修改组成员

向群组中添加或移除联系人：

POST /google-contacts/v1/contactGroups/{resourceName}/members:modify
Content-Type: application/json

{
  "resourceNamesToAdd": ["people/c123", "people/c456"],
  "resourceNamesToRemove": ["people/c789"]
}

其他联系人

其他联系人是指您曾与之互动（例如通过电子邮件）但未明确添加到通讯录中的人员。

列出其他联系人

GET /google-contacts/v1/otherContacts?readMask=names,emailAddresses&pageSize=100

将其他联系人复制到“我的联系人”

POST /google-contacts/v1/{resourceName}:copyOtherContactToMyContactsGroup
Content-Type: application/json

{
  "copyMask": "names,emailAddresses,phoneNumbers"
}

人员字段

这些字段可与personFields或readMask参数配合使用：

多个字段：personFields=姓名,电子邮件地址,电话号码,组织

分页

使用pageSize和pageToken进行分页：

GET /google-contacts/v1/people/me/connections?personFields=names&pageSize=100&pageToken=NEXT_PAGE_TOKEN

响应包含分页信息：

{
  "connections": [...],
  "totalPeople": 500,
  "nextPageToken": "...",
  "nextSyncToken": "..."
}

继续使用pageToken直到nextPageToken未返回。

代码示例

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

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、全部，已阻止
• 该personFields参数在大多数读取操作中是必需的
• 更新联系人时，请包含etag以防止覆盖并发更改
• 针对同一用户的变更请求应按顺序发送，以避免延迟增加和失败
• 重要提示：使用 curl 命令时，若 URL 包含方括号，请使用curl -g以禁用通配符解析
• 重要提示：当将 curl 输出通过管道传输到jq或其他命令时，在某些 shell 环境中，诸如$MATON_API_KEY之类的环境变量可能无法正确展开

错误处理

故障排除：API密钥问题

1. 请检查MATON_API_KEY环境变量是否已设置：

echo $MATON_API_KEY

2. 通过列出连接来验证API密钥是否有效：

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 概览
• People 资源
• 联系人组资源
• Person 字段参考
• Maton 社区
• Maton 技术支持