# XDK - X 开发者套件适用于 X API v2 的官方 TypeScript 和 Python SDK。两个 SDK 均根据相同的 OpenAPI 规范生成，并共享相同的 API 覆盖范围。 |打字稿 |蟒蛇 ---|---|--- **套餐** | `@xdevplatform/xdk` | `xdk` **安装** | `npm install @xdevplatform/xdk` | `pip 安装 xdk` **运行时** | Node.js 16+、TypeScript 4.5+ | Python 3.8+ **回购** | [github.com/xdevplatform/xdk]() | [github.com/xdevplatform/xdk]() **样品** | [样本/javascript]() | [样本/python]() ## 快速入门 ### 打字稿从'@xdevplatform/xdk'导入{客户端，输入ClientConfig}； const client = new Client({ bearerToken: process.env.X_API_BEARER_TOKEN }); const 响应 = 等待 client.users.getByUsername('XDevelopers', { 用户字段：['描述'，'public_metrics']， }); console.log(response.data?.用户名); ###Python 导入操作系统从 xdk 导入客户端客户端 = 客户端(bearer_token=os.getenv("X_API_BEARER_TOKEN")) 对于 client.posts.search_recent(query="python", max_results=10) 中的页面：如果页面数据：打印（页.数据[0].文本）打破 ## 客户端架构两个 SDK 都公开了一个带有专门子客户端的主“客户端”：子客户端|目的 ---|--- `client.posts` |搜索、创建、删除、查找、分析、点赞、转发、引用推文 `客户端.用户` |查找、关注/取消关注、阻止/静音、时间线、提及 `client.stream` |过滤流、采样流、Firehose、规则管理 `客户端.媒体` |上传（分块）、元数据、字幕、分析 `client.lists` |创建、管理成员、获取推文列表 `client.directMessages` |发送/接收 DM、管理对话 `client.spaces` |从 Spaces 查找、搜索、获取帖子 `客户社区` |搜索，通过ID获取社区 `client.communityNotes` |创建、评估、搜索笔记 `客户趋势` |作者：WOEID，个性化，AI趋势 `client.webhooks` |创建、管理、重播 Webhooks `客户端.合规性` |合规职位 `client.usage` | API使用统计 `客户端活动` |活动订阅和流媒体 `client.accountActivity` |账户活动API `client.connections` |连接管理 `客户新闻` |新闻搜索和查找 ## 身份验证三种方法，都是 SDK： ### 1\.不记名令牌（仅限应用程序）- 只读公共数据 // 打字稿 const client = new Client({ bearerToken: 'YOUR_TOKEN' }); # Python 客户端=客户端（bearer_token =“YOUR_TOKEN”） ### 2\. OAuth 2.0 PKCE - 用户上下文操作（推荐） // 打字稿从'@xdevplatform/xdk'导入{Client，OAuth2，generateCodeVerifier，generateCodeChallenge}；常量 oauth2 = 新 OAuth2({ clientId: '您的客户 ID', clientSecret: '您的客户秘密', redirectUri: 'https://example.com/callback', 范围: ['tweet.read', 'users.read', 'offline.access'], }); const codeVerifier =generateCodeVerifier(); const codeChallenge =等待generateCodeChallenge(codeVerifier); oauth2.setPkceParameters(codeVerifier, codeChallenge); const authUrl = 等待 oauth2.getAuthorizationUrl('state'); // 用户授权->回调返回code const tokens = wait oauth2.exchangeCode(authCode, codeVerifier); const client = new Client({ accessToken: tokens.access_token }); # Python 从 xdk.oauth2_auth 导入 OAuth2PKCEAuth 身份验证 = OAuth2PKCEAuth( client_id="YOUR_CLIENT_ID", redirect_uri="YOUR_CALLBACK_URL", 范围=“推文.读取用户.读取离线.访问” ） auth_url = auth.get_authorization_url() # 用户授权->回调返回URL 令牌 = auth.fetch_token(authorization_response=callback_url) 客户端 = 客户端(bearer_token=tokens["access_token"]) ### 3\. OAuth 1.0a - 旧用户上下文 // 打字稿从 '@xdevplatform/xdk' 导入 { Client, OAuth1 }; 常量 oauth1 = 新 OAuth1({ apiKey: '密钥', apiSecret: '秘密', accessToken: '令牌', accessTokenSecret: '令牌秘密', }); const client = new Client({ oauth1 }); # Python 从 xdk 导入客户端从 xdk.oauth1_auth 导入 OAuth1 oauth1 = OAuth1( api_key="密钥", api_secret="秘密", access_token =“令牌”，access_token_secret =“令牌秘密”，）客户端 = 客户端（auth=oauth1） ## 字段和扩展 X API 默认返回最少的数据（“id”、“text”）。始终请求您需要的字段。 // TypeScript - 获取带有作者信息的帖子 const post = 等待 client.posts.getById('123456', { tweetFields: ['created_at', 'public_metrics', 'author_id'], 扩展：['author_id', 'attachments.media_keys'], userFields: ['用户名', '姓名', '个人资料图像网址'], mediaFields: ['url', 'preview_image_url', '类型'], }); // post.data = 帖子，post.includes.users = 扩展作者 # Python - 使用字段搜索对于 client.posts.search_recent 中的页面（查询=“蟒蛇”，最大结果=100， tweet_fields=["created_at", "public_metrics", "author_id"], 扩展=["author_id"], user_fields=["用户名", "姓名"], ）：对于 page.data 中的帖子：打印（post.text，post.public_metrics）常见扩展：`author_id`、`referenced_tweets.id`、`attachments.media_keys`、`in_reply_to_user_id`、`geo.place_id`。 ## 分页 ### TypeScript - 具有异步迭代的分页器包装器从 '@xdevplatform/xdk' 导入 { Client、UserPaginator、PaginatedResponse、Schemas }； const client = new Client({ bearerToken: 'token' }); const 关注者 = new UserPaginator( 异步（令牌？：字符串）：Promise> => { const res = 等待 client.users.getFollowers('userId', { 最大结果：100，分页令牌：令牌， userFields: ['id', '姓名', '用户名'], }); 返回 { 数据：res.data ?? []，元：res.meta，包含：res.includes，错误：res.errors }; } ）； // 异步迭代（推荐） for等待（关注者的const用户）{ console.log(用户.用户名); } // 或者手动分页等待关注者.fetchNext(); while (!followers.done) { 等待关注者.fetchNext(); } console.log(followers.users.length); ### Python - 基于迭代器（自动） # 自动 - SDK 处理 next_token 所有帖子 = [] 对于 client.posts.search_recent(query="python", max_results=100) 中的页面： all_posts.extend(page.data) # 手动 - 自己提取 next_token 第一页 = 下一页(client.posts.search_recent(query="xdk", max_results=100)) next_token = first_page.meta.next_token 如果first_page.meta 否则无 ## 流媒体 X API 提供了多个实时流端点。根据您的用例进行选择：流类型|方法|所需规则 |卷 |访问 ---|---|---|---|--- **过滤流** | `client.stream.posts()` | **是的 - 必须先添加规则** |仅匹配帖子 |全部 **采样流 (1%)** | `client.stream.postsSample()` |没有 | ~1% 随机样本 |全部 **采样流 (10%)** | `client.stream.postsSample10()` |没有 | ~10% 随机样本 |企业 **消防水带** | `client.stream.postsFirehose()` |没有 |所有帖子 |企业 **重要提示：如果没有规则，过滤后的流将不会提供任何内容。** 在连接之前，您必须至少添加一条规则。没有规则的连接会产生一个没有错误的静默空流。 ### 过滤流工作流程正确的顺序始终是：**添加规则 -> 连接 -> 处理帖子**。 // 打字稿 // 第 1 步：在连接之前添加规则等待 client.stream.updateRules({ 添加：[{ value: 'from:xdevelopers -is:retweet', tag: '官方' }], }); // 第 2 步：连接到流 const 流 = 等待 client.stream.posts({ tweetFields: ['id', 'text', 'created_at'], 扩展：['author_id'], userFields: ['用户名'], }); // 第三步：消费事件 Stream.on('数据', (事件) => { console.log(event.data?.text); console.log('匹配规则：', event.matching_rules); }); Stream.on('错误', (e) => console.error(e)); // 或者使用异步迭代 for等待（流的常量事件）{ 控制台.log(事件); } // 完成后总是关闭流.close(); # Python 从 xdk.stream.models 导入 UpdateRulesRequest # 第 1 步：在连接之前添加规则请求 = UpdateRulesRequest(**{ "add": [{"value": "from:xdevelopers -is:retweet", "tag": "official"}] }) client.stream.update_rules(body=请求) # 第 2 步：连接并消费对于 client.stream.posts() 中的 post_response：数据 = post_response.model_dump() 如果数据和数据中的“数据”['数据']：打印（数据['数据'].get（'文本'，''）） ### 采样流（无需规则） // TypeScript - 所有帖子的 1% 随机样本 const 流 = 等待 client.stream.postsSample({ tweetFields: ['id', 'text', 'created_at'], }); for等待（流的常量事件）{ 控制台.log(事件); } # Python - 1% 随机样本对于 client.stream.posts_sample() 中的帖子：数据 = post.model_dump() 如果数据和数据中的“数据”['数据']：打印（数据['数据'].get（'文本'，''）） ### 连接管理 * Streams 每 20 秒发送一次 **keep-alive 心跳** \-- 如果 20 秒内没有任何消息到达，则重新连接 * **预计会断开连接**（服务器重新启动、网络问题、缓冲区溢出）--始终实现重新连接逻辑 * 过滤流仅允许 **1 个并发连接**（按使用付费） * 您可以**添加/删除规则，而无需断开**与流的连接 * **将摄取与处理分离** \-- 在流读取器和处理逻辑之间使用 FIFO 队列有关详细的流模式、重新连接策略和规则构建指南，请参阅 [api-concepts.md]()。 ## 已知问题 ### OAuth1 正文读取错误 (TypeScript XDK) **错误：** 使用 OAuth1 身份验证时，XDK 读取请求正文流以计算 OAuth1 签名。当“fetch()”尝试发送请求时，主体流已被消耗，导致：“错误[ApiError]：主体不可用：主体已被读取” **受影响的调用**（二进制/大型正文数据）： * `client.media.upload()`（一次性上传）——总是失败 * `client.media.appendUpload()`（分块 APPEND）——总是失败 **不受影响的调用**（小 JSON 或无正文）： * `client.posts.create()` \-- 工作正常 * `client.media.initializeUpload()` \-- 工作正常（仅元数据） * `client.media.finalizeUpload()` \-- 工作正常（无正文） **解决方法：** 使用混合方法 - 对所有有效端点使用带有 OAuth1 的 XDK，并仅对 APPEND 步骤使用带有手动 OAuth1 标头签名的直接“获取”。 INIT、FINALIZE 和 POST 步骤都正常通过 XDK。请参阅“媒体上传（OAuth1 解决方法）”下的 [typescript-patterns.md]() 中的完整工作实现。 ## 最佳实践 1. **始终指定字段** \- 切勿依赖默认值。准确请求您需要的内容，以最大限度地减少有效负载和计费。 2. **使用扩展** \- 在一次调用中获取相关对象（作者、媒体），而不是多次请求。 3. **环境变量** \- 切勿硬编码令牌。使用“process.env”(TS) 或“os.getenv”(Python)。 4. **处理速率限制** \- 检查 `x-rate-limit-remaining` 标头。对 429 错误使用退避。 Python SDK 自动处理分页的速率限制退避。 5. **使用流而不是轮询** \- 对于实时数据，使用过滤流而不是重复的搜索调用。 6. **关闭流** \- 完成后始终关闭流连接以避免资源泄漏。 7. **对大型结果进行分页** \- 使用异步迭代（TS）或迭代器（Python）进行自动分页。 8. **使用 max_results** \- 将 `max_results` 设置为允许的最大值，以最大限度地减少 API 调用。 9. **缓存响应** \- 将结果存储在本地以减少重复请求。 10. **使用 TypeScript 类型** \- 导入 `Schemas.*` 类型以确保编译时安全。 ## 错误处理 // 打字稿从'@xdevplatform/xdk'导入{ApiError}；尝试{ const post =等待 client.posts.getById('123'); } 捕获（错误）{ if (ApiError 错误实例) { console.error(`API 错误 ${error.statusCode}: ${error.message}`); } } # Python 尝试：响应 = client.posts.get_by_id(id="123") 除了异常 e：打印（f“错误：{e}”） ## 其他资源 * 有关详细的 TypeScript 模式，请参阅 [typescript-patterns.md]() * 有关详细的Python模式，请参阅[python-patterns.md]() * 有关核心 X API 概念（响应结构、速率限制、搜索运算符），请参阅 [api-concepts.md]() * 完整的 X API 文档：[xdevplatform/docs/x-api]() * 完整的 SDK 参考文档：[xdevplatform/docs/xdks]() * XDK 来源：[xdevplatform/xdk]() * 代码示例：[xdevplatform/samples]()

Xdev平台Xdk

包含技能