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