--- metadata: - name: generator content: Diplodoc Platform v5.55.0 alternate: - https://yandex.com/dev/market/partner-api/doc/en/concepts/best-practices.md - https://yandex.com/dev/market/partner-api/doc/ru/concepts/best-practices.md - https://yandex.com/dev/market/partner-api/doc/zh/concepts/best-practices.md - href: zh/concepts/best-practices.md type: text/markdown title: Markdown version - href: ../llms.txt type: text/markdown title: llms.txt --- > **Documentation Index:** Fetch the complete configuration index at https://yandex.com/dev/market/partner-api/doc/zh/llms.txt # 与......集成的最佳实践 Yandex Market API 卖家须知 此页面面向开发人员和技术专家，他们创建、维护或支持与 Yandex Market API. 文章的目的 — 帮助构建与 Yandex Market API，在负载下稳定工作，确保存储数据的安全处理。 ## 整合的一般原则 - 仅请求当前场景需要的数据。 - 遵循请求限制并随着时间的推移平均分配负载。 - 使用API通知而不是频繁的方法轮询。 - 通过集成方法和方案跟踪错误率 - 根据安全要求设计集成 ## 使用API方法 ### 设计集成以适应变化 - 只处理脚本需要的字段，并跳过不熟悉的元素和字段。 - 不要依赖于字段的顺序，以其名称为指导。 - 对于枚举（状态、类型等），为未知值提供默认值，并防止它们由于解析错误而下降。 - 使用最新信息定期更新客户端模型。 [规格说明 OpenAPI](https://yandex.com/dev/market/partner-api/doc/zh/concepts/openapi.md)：使用最新版本的规范 [与 GitHub](https://github.com/yandex-market/yandex-market-partner-api) 重新组装客户端 - 关注空气污染指数新闻 [更新历史](https://yandex.com/dev/market/partner-api/doc/zh/changelog/all.md) 并在文档和规范中注意到方法的过时 - 计划切换到新方法，直到过时的方法完全禁用，以避免集成失败。 ### 仅请求必要的数据 - 按更改时间、状态和实体类型使用方法筛选器。 - 将样本调整到特定场景，而不是从方法请求完整的数据集。 - 尝试优化集成，以便您不会发出不必要的API请求。 例子：: - [查看柜内产品](https://yandex.com/dev/market/partner-api/doc/zh/reference/business-offer-mappings/getOfferMappings.md) - [订单清单](https://yandex.com/dev/market/partner-api/doc/zh/reference/orders/getBusinessOrders.md) ### 正确处理分页 `pageToken` - 通过字段确定下一页**仅**的存在 `nextPageToken` 在响应中，而不是按当前页面上的项目数 - 响应中的行的数量可以小于发送的或预期的数量。 `limit` （例如，如果值 `limit` 自动降低到允许的最大值） — 这并不意味着没有更多的数据。 - 只要有响应，就继续提出请求。 `nextPageToken`;如果没有参数 — 这是最后一页 [分页的工作原理](https://yandex.com/dev/market/partner-api/doc/zh/concepts/pagination.md) ## 可靠性、错误和限制 ### 分离4xx和5xx并设置重复 - 设置5xx响应和网络故障的重播 - 在重复之间暂停，以指数方式增加它们的持续时间，并在每次重复时添加一个小的随机延迟。 - 不要重复4xx响应：修复客户端错误的原因，而不是重新发送请求。 - 随着4xx份额的增长，检查查询的正确性：参数，数据模式和使用的方法的相关性。 [返回的错误说明 Yandex Market API](https://yandex.com/dev/market/partner-api/doc/zh/concepts/error-codes.md) ### 配置集成的网络设置 - 设置足够的连接和读取超时 — 超时不足会导致499错误（客户端关闭请求） - 使用速率限制器或任务队列在一段时间内均匀分布请求，避免流量峰值，并避免超出限制。 [使用限制的描述](https://yandex.com/dev/market/partner-api/doc/zh/concepts/limits.md) ### 启用日志记录和错误监控 - 有关方法调用的日志信息：状态、标头以及请求和响应主体 - 保留唯一的请求ID。 `traceparent` 要在部分中搜索 [请求日志](https://yandex.com/dev/market/partner-api/doc/zh/concepts/debug.md) — 这将帮助你和Yandex的。市场支持服务快速找到特定的分析请求. - 按类型分组错误(400 — 参数不正确, 401/403 — 授权和访问权限，404 — 缺少资源，420 — 超出限制，等等），随着时间的推移跟踪它们的份额，并通过方法和类型构建具有错误的仪表板，以快速注意峰值。 - 根据错误阈值（例如，特定方法的404增加）设置警报，以便在故障开始影响商店的操作之前接收通知并采取措施。 ## 授权和安全 ### 使用最新的授权方案和最小的访问权限 - 使用授权方案 **Api-密钥** 对于卖方集成 - 将密钥访问限制在操作所需的最小值。 - 创建单独的 **Api-密钥** 对于不同的集成，并为每个配置最小必要的访问，以限制在泄漏的情况下可能的损坏。 - 要接收通知，请确保请求仅来自受信任的Yandex IP地址。 [受信任的IP地址列表](https://yandex.ru/dev/market/partner-api/doc/ru/push-notifications/) [如何设置Api密钥](https://yandex.com/dev/market/partner-api/doc/zh/concepts/api-key.md) [通过Api密钥访问方法](https://yandex.com/dev/market/partner-api/doc/zh/concepts/access.md) ### 确保钥匙的安全存储和使用 - 将授权密钥和令牌保存在秘密存储库中，不要将它们添加到源代码、日志和通信中。 - 定期查看活动密钥列表，删除未使用的密钥，并在更改承包商或集成商时更改密钥。 ## 方案的最佳实践 ### 命令 - 要接收更改的订单，请使用更新时间参数和有限的间隔。 - 使用基于创建时间、状态和其他参数的筛选器，仅接收特定方案的必要订单。 - 对订单事件使用API通知，而不是频繁的请求。 [接收订单](https://yandex.com/dev/market/partner-api/doc/zh/step-by-step/orders-receive.md) ### 余额和价格 - 定期发送更改职位的信息。 - 只发送更改的项目，而不是全部范围。 - 将更改分组为可接受大小的批量请求，并避免大量小请求。 - 从单一数据源同步余额和价格，以避免销售渠道之间的差异。 [剩菜转让](https://yandex.com/dev/market/partner-api/doc/zh/reference/stocks/updateStocks.md) ### 分类及产品卡 - 使用足够大的分页以避免执行数千个短查询。 - 为业务需求安排更新，而不是比实际需要的更频繁。 - 添加和更改分类时，请务必检查错误列表。 **结果。错误** 和评论 **结果。警告** 在响应中：如果存在错误，则不会应用所有传输项目的更改。 ### 报告和分析 - 对于长时间的分析，请使用异步报告。 - 按计划计划报告的生成和下载，随着时间的推移均匀分布查询，并将结果保存在本地，直到下一次重新生成。 - 仅请求那些类型的报告，并且仅针对卖家的场景真正需要的商店。 - 请注意，报告的结构和内容可能会更改，恕不另行通知：可能会出现一个新的列或工作表的名称可能会更改。 ### 通知书 - 通过快速响应确认收到通知。 - 将进一步的事件处理发送到队列并异步执行。 - 如果不接受通知，则在响应中发送错误。 [如何使用通知](https://yandex.com/dev/market/partner-api/doc/zh/push-notifications/index.md)