介绍
# Google Play
使用托管的 OAuth 身份验证访问 Google Play Developer API (Android Publisher)。管理应用列表、订阅、应用内购买、评论等。
## Quick Start
```bash # List in-app products python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-play/androidpublisher/v3/applications/{packageName}/inappproducts') 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-play/{native-api-path} ```
将 `{native-api-path}` 替换为实际的 Android Publisher API 端点路径。网关将请求代理到 `androidpublisher.googleapis.com` 并自动注入您的 OAuth 令牌。
## Authentication
所有请求都需要在 Authorization header 中包含 Maton API key：
``` Authorization: Bearer $MATON_API_KEY ```
**Environment Variable:** 将您的 API key 设置为 `MATON_API_KEY`：
```bash export MATON_API_KEY="YOUR_API_KEY" ```
### Getting Your API Key
1. 登录或在 [maton.ai](https://maton.ai) 创建账户 2. 前往 [maton.ai/settings](https://maton.ai/settings) 3. 复制您的 API key
## Connection Management
在 `https://ctrl.maton.ai` 管理您的 Google OAuth 连接。
### List Connections
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://ctrl.maton.ai/connections?app=google-play&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 ```
### Create Connection
```bash python <<'EOF' import urllib.request, os, json data = json.dumps({'app': 'google-play'}).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 ```
### Get Connection
```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 ```
**Response:** ```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-play", "metadata": {} } } ```
在浏览器中打开返回的 `url` 以完成 OAuth 授权。
### Delete Connection
```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 ```
### Specifying Connection
如果您有多个 Google Play 连接，请使用 `Maton-Connection` header 指定要使用的连接：
```bash python <<'EOF' import urllib.request, os, json req = urllib.request.Request('https://gateway.maton.ai/google-play/androidpublisher/v3/applications/{packageName}/inappproducts') 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 Reference
### In-App Products
#### List In-App Products
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/inappproducts ```
#### Get In-App Product
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/inappproducts/{sku} ```
#### Create In-App Product
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/inappproducts Content-Type: application/json
{ "packageName": "com.example.app", "sku": "premium_upgrade", "status": "active", "purchaseType": "managedUser", "defaultPrice": { "priceMicros": "990000", "currency": "USD" }, "listings": { "en-US": { "title": "Premium Upgrade", "description": "Unlock all premium features" } } } ```
#### Update In-App Product
```bash PUT /google-play/androidpublisher/v3/applications/{packageName}/inappproducts/{sku} Content-Type: application/json
{ "packageName": "com.example.app", "sku": "premium_upgrade", "status": "active", "purchaseType": "managedUser", "defaultPrice": { "priceMicros": "1990000", "currency": "USD" } } ```
#### Delete In-App Product
```bash DELETE /google-play/androidpublisher/v3/applications/{packageName}/inappproducts/{sku} ```
### Subscriptions
#### List Subscriptions
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/subscriptions ```
#### Get Subscription
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/subscriptions/{productId} ```
#### Create Subscription
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/subscriptions Content-Type: application/json
{ "productId": "monthly_premium", "basePlans": [ { "basePlanId": "p1m", "autoRenewingBasePlanType": { "billingPeriodDuration": "P1M" } } ], "listings": [ { "languageCode": "en-US", "title": "Premium Monthly" } ] } ```
### Purchases
#### Get Purchase (one-time product)
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token} ```
#### Acknowledge Purchase
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/purchases/products/{productId}/tokens/{token}:acknowledge Content-Type: application/json
{ "developerPayload": "optional payload" } ```
#### Get Subscription Purchase
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token} ```
#### Cancel Subscription
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:cancel ```
#### Refund Subscription
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/purchases/subscriptions/{subscriptionId}/tokens/{token}:refund ```
### Reviews
#### List Reviews
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/reviews ```
#### Get Review
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/reviews/{reviewId} ```
#### Reply to Review
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/reviews/{reviewId}:reply Content-Type: application/json
{ "replyText": "Thank you for your feedback!" } ```
### Edits (App Updates)
#### Create Edit
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/edits ```
#### Get Edit
```bash GET /google-play/androidpublisher/v3/applications/{packageName}/edits/{editId} ```
#### Commit Edit
```bash POST /google-play/androidpublisher/v3/applications/{packageName}/edits/{editId}:commit ```
#### Delete Edit
```bash DELETE /google-play/androidpublisher/v3/applications/{packageName}/edits/{editId} ```
## Code Examples
### JavaScript
```javascript // List in-app products const packageName = 'com.example.app'; const response = await fetch( `https://gateway.maton.ai/google-play/androidpublisher/v3/applications/${packageName}/inappproducts`, { headers: { 'Authorization': `Bearer ${process.env.MATON_API_KEY}` } } );
const products = await response.json(); console.log(products); ```
### Python
```python import os import requests
headers = {'Authorization': f'Bearer {os.environ["MATON_API_KEY"]}'} package_name = 'com.example.app'
# List in-app products response = requests.get( f'https://gateway.maton.ai/google-play/androidpublisher/v3/applications/{package_name}/inappproducts', headers=headers ) products = response.json() print(products) ```
## Notes
- 将 `{packageName}` 替换为您的应用包名（例如 `com.example.app`） - Google Play Developer API 要求应用必须已在 Google Play 上发布 - 订阅管理要求应用已配置活动订阅 - 编辑 是事务性的 - 创建一个编辑，进行更改，然后提交 - IMPORTANT: 使用 curl 命令时，如果 URL 包含括号（`fields[]`、`sort[]`、`records[]`），请使用 `curl -g` 以禁用 glob 解析 - IMPORTANT: 将 curl 输出通过管道传输到 `jq` 或其他命令时，像 `$MATON_API_KEY` 这样的环境变量在某些 shell 环境中可能无法正确展开。通过管道传输时，您可能会遇到“Invalid API key”错误。
## Error Handling
| Status | Meaning | |--------|---------| | 400 | 缺少 Google Play 连接 | | 401 | Maton API key 无效或缺失 | | 404 | 未找到包或无访问权限 | | 429 | 速率受限 (每个账户 10 次/秒) | | 4xx/5xx | 来自 Google Play API 的透传错误 |
### Troubleshooting: API Key Issues
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 ```
### Troubleshooting: Invalid App Name
1. 确保您的 URL 路径以 `google-play` 开头。例如：
- Correct: `https://gateway.maton.ai/google-play/androidpublisher/v3/applications/{packageName}/inappproducts` - Incorrect: `https://gateway.maton.ai/androidpublisher/v3/applications/{packageName}/inappproducts`
## Resources
- [Android Publisher API Overview](https://developers.google.com/android-publisher) - [In-App Products](https://developers.google.com/android-publisher/api-ref/rest/v3/inappproducts) - [Subscriptions](https://developers.google.com/android-publisher/api-ref/rest/v3/monetization.subscriptions) - [Purchases](https://developers.google.com/android-publisher/api-ref/rest/v3/purchases.products) - [Reviews](https://developers.google.com/android-publisher/api-ref/rest/v3/reviews) - [Edits](https://developers.google.com/android-publisher/api-ref/rest/v3/edits) - [Maton Community](https://discord.com/invite/dBfFAcefs2) - [Maton Support](mailto:[email protected])