📦 LinkedIn API — 社交网络

通过托管 OAuth 认证访问 LinkedIn API。分享帖子、管理广告活动、检索个人资料和组织信息、上传媒体、访问广告库。

快速开始

# 获取当前用户个人资料
python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

基础 URL

https://gateway.maton.ai/linkedin/rest/{resource}

网关将请求代理到 api.linkedin.com 并自动注入您的 OAuth token。

认证

所有请求都需要在 Authorization 头中包含 Maton API 密钥：

Authorization: Bearer $MATON_API_KEY

环境变量: 将您的 API 密钥设置为 MATON_API_KEY：

export MATON_API_KEY="YOUR_API_KEY"

获取 API 密钥

• 在 maton.ai 登录或创建账户
• 访问 maton.ai/settings
• 复制您的 API 密钥

必需的请求头

LinkedIn REST API 需要版本头：

LinkedIn-Version: 202506

连接管理

在 https://ctrl.maton.ai 管理您的 LinkedIn OAuth 连接。

列出连接

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://ctrl.maton.ai/connections?app=linkedin&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': 'linkedin'}).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": "ba10eb9e-b590-4e95-8c2e-3901ff94642a",
    "status": "ACTIVE",
    "creation_time": "2026-02-07T08:00:24.372659Z",
    "last_updated_time": "2026-02-07T08:05:16.609085Z",
    "url": "https://connect.maton.ai/?session_token=...",
    "app": "linkedin",
    "metadata": {}
  }
}

在浏览器中打开返回的 url 完成 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

指定连接

如果您有多个 LinkedIn 连接，请使用 Maton-Connection 头指定要使用的连接：

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
req.add_header('Maton-Connection', 'ba10eb9e-b590-4e95-8c2e-3901ff94642a')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

如果省略，网关将使用默认（最早的）活动连接。

个人资料 API

获取当前用户资料

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/me')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

响应示例:

{
  "id": "123ABC",
  "firstName": {
    "localized": {
      "en_US": "John"
    }
  },
  "lastName": {
    "localized": {
      "en_US": "Doe"
    }
  },
  "profilePicture": {
    "displayImage": "urn:li:digitalmediaAsset:..."
  }
}

获取组织信息

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/organizations/{organization_id}')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

分享 API

创建文本帖子

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "author": "urn:li:person:123ABC",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "shareCommentary": {
                "text": "Check out this amazing article about AI!"
            },
            "shareMediaCategory": "NONE"
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "PUBLIC"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/ugcPosts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
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
data = json.dumps({
    "author": "urn:li:person:123ABC",
    "lifecycleState": "PUBLISHED",
    "specificContent": {
        "com.linkedin.ugc.ShareContent": {
            "shareCommentary": {
                "text": "Great read on machine learning trends in 2024"
            },
            "shareMediaCategory": "ARTICLE",
            "media": [
                {
                    "status": "READY",
                    "originalUrl": "https://example.com/article",
                    "title": {
                        "text": "ML Trends 2024"
                    }
                }
            ]
        }
    },
    "visibility": {
        "com.linkedin.ugc.MemberNetworkVisibility": "CONNECTIONS"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/ugcPosts', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
req.add_header('Content-Type', 'application/json')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

广告 API

获取广告账户列表

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/adAccounts?q=search&search=')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

创建广告活动

python <<'EOF'
import urllib.request, os, json
data = json.dumps({
    "name": "Summer Campaign 2024",
    "account": "urn:li:sponsoredAccount:123456",
    "objectiveType": "LEAD_GENERATION",
    "runSchedule": {
        "start": "2024-06-01",
        "end": "2024-08-31"
    },
    "dailyBudget": {
        "amount": 100,
        "currencyCode": "USD"
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/adCampaignsV2', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
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
data = json.dumps({
    "initializeUploadRequest": {
        "owner": "urn:li:person:123ABC",
        "recipes": ["urn:li:digitalmediaRecipe:feedshare-image"],
        "serviceRelationships": [
            {
                "relationshipType": "OWNER",
                "identifier": "urn:li:userGeneratedContent"
            }
        ]
    }
}).encode()
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/media/upload', data=data, method='POST')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
req.add_header('Content-Type', 'application/json')
response = json.load(urllib.request.urlopen(req))
print(json.dumps(response, indent=2))
upload_url = response['value']['uploadMechanism']['com.linkedin.digitalmedia.uploading.MediaUploadHttpRequest']['uploadUrl']
asset_urn = response['value']['asset']
EOF

• 上传二进制文件:

# 使用返回的 upload_url 直接上传（不通过网关）
python <<'EOF'
import urllib.request
with open('image.jpg', 'rb') as f:
    data = f.read()
req = urllib.request.Request(upload_url, data=data, method='PUT')
req.add_header('Content-Type', 'image/jpeg')
urllib.request.urlopen(req)
EOF

• 创建帖子时引用图片:

# 在帖子中使用 asset_urn

广告库 API

搜索广告

python <<'EOF'
import urllib.request, os, json
req = urllib.request.Request('https://gateway.maton.ai/linkedin/rest/adLibrary/search?q=search&keywords=AI')
req.add_header('Authorization', f'Bearer {os.environ["MATON_API_KEY"]}')
req.add_header('LinkedIn-Version', '202506')
print(json.dumps(json.load(urllib.request.urlopen(req)), indent=2))
EOF

Little Text Format 转义

LinkedIn 的评论字段使用 Little Text Format，某些字符需要转义：

话题标签（简单格式）: #话题（仅限单个单词）

Python 辅助函数

def escape_linkedin_commentary(text):
    """转义 LinkedIn Little Text Format 的保留字符。"""
    reserved = ['\\', '|', '{', '}', '@', '[', ']', '(', ')', '<', '>', '#', '', '_', '~']
    for char in reserved:
        text = text.replace(char, '\\' + char)
    return text
# 使用示例
commentary = escape_linkedin_commentary("Check this out! Details (inside) #tech")
# 结果: "Check this out\\! Details \\(inside\\) \\#tech"

注意事项

• 人员 ID 是每个应用唯一的，不能跨应用转移
• 评论使用 Little Text Format — 使用反斜杠转义保留字符 (\|{}@[]()<>#*_~)，否则内容会被截断
• author 字段必须使用 URN 格式: urn:li:person:{personId}
• 所有帖子都需要 lifecycleState: "PUBLISHED"
• 图片上传是一个三步过程：初始化、上传二进制文件、创建帖子
• 视频上传是一个四步过程：初始化、上传二进制文件、完成、创建帖子
• 媒体上传 URL（图片、视频、文档）指向 www.linkedin.com，而不是 api.linkedin.com。 这些是预签名 URL，不通过网关，不需要 Authorization 头。您必须使用 Python urllib 来处理这些 URL — 不要通过 shell 变量传递或使用 curl，因为 URL 包含会被 shell 扩展破坏的编码字符 (%253D)。
• 所有 REST API 调用都包含 LinkedIn-Version: 202506 头
• 个人资料图片 URL 可能过期；如果需要请重新获取

错误处理

错误响应格式

{
  "status": 403,
  "serviceErrorCode": 100,
  "code": "ACCESS_DENIED",
  "message": "Not enough permissions to access resource"
}

故障排除：API 密钥问题

• 检查 MATON_API_KEY 环境变量是否设置：

echo $MATON_API_KEY

• 通过列出连接验证 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

故障排除：应用名称无效

• 确保您的 URL 路径以 linkedin 开头。例如：

• 正确: https://gateway.maton.ai/linkedin/rest/me
• 错误: https://gateway.maton.ai/rest/me

OAuth 作用域

资源链接

• LinkedIn API 概述
• LinkedIn 分享指南
• 个人资料 API
• LinkedIn 登录
• 认证指南
• 营销 API
• 广告账户
• 广告活动管理
• 广告库 API
• Maton 社区
• Maton 支持