Smartsheet API最佳实践

在设计和构建API集成的过程中，很容易将注意力集中在操作、属性和参数的细节上，而忽略了可能显著影响集成的性能、稳定性和可维护性的因素。给予这些因素应有的关注可能意味着不可靠的集成和坚如磐石的集成之间的区别。

这篇文章重点介绍了以下4个Smartsheet API最佳实践:

• 是有效的:使用“bulk”启用的操作

• 是实用的:遵守费率限制准则

• 是聪明的恰当地处理错误

• 要勤奋:实现日志记录

我们强烈建议您在设计集成时牢记这些指导方针。

高效:使用“批量”操作

为了提高效率，我们建议您尽可能使用支持大容量的API操作。支持大容量的API操作允许您使用单个API请求添加、更新或删除多个项。例如，如果需要在一个工作表中更新10行，请使用单个行进行更新更新行(年代)请求，而不是执行10个单独的请求——每行一个。

支持批量操作的操作大大减少了必须拨打的外呼数量，从而提高了效率，减少了呼叫失败的机会速率限制(因为每个大容量操作只算一个接近极限的请求)，并减轻我们系统上的负载，使您的请求更有可能及时完成。

以下API操作目前允许你批量操作:

• 添加列(年代)

• 添加最喜欢的(年代)

• 删除最喜欢的(s)

• 添加组成员

• 添加行(年代)

• 复制一行到另一个工作表

• 删除行(年代)

• 将行移动到另一个工作表

• 通过电子邮件发送行

• 更新行(年代)

我们将在未来添加更多支持“批量”的操作，因此请留意那些额外的机会来提高效率，并尽可能地进行批量操作。

实际一点:遵守费率限制准则

处理“超过速率限制”错误
Smartsheet API目前强加了一个速率限制每个访问令牌每分钟300个请求。(我们保留随时更改此限制的权利。)某些资源密集型操作，例如附加文件或获取手机历史记录，按速率限制计算为10个请求。如果超过此速率限制，后续API请求(在一分钟内)将返回429HTTP状态码，以及以下JSON响应体:

{" errorCode ": 4003， " message ": "速率限制超过。""}

请注意: API 2.0返回HTTP状态码429对于这个速率限制误差。在API 1.1中，它作为HTTP状态代码返回503．

我们建议您将集成设计为优雅地处理这种速率限制错误。一种方法是在遇到此错误时让集成休眠60秒，然后重试请求。或者，您可以选择实现指数倒扣(一种错误处理策略，您可以定期重试失败的请求，重试之间的等待时间逐渐变长，直到请求成功或达到一定的重试尝试次数)。

重要提示:避免执行“快速”更新
此外，我们强烈建议您避免快速连续地执行API请求来在很短的时间内一遍又一遍地更新特定的Smartsheet对象。例如，如果您的集成所做的唯一事情是执行更新行(年代)每秒请求一次相同的表，这相当于每分钟总共只有60个请求——完全在速率限制准则之内。然而，如此快速地连续更新同一个对象可能会导致保存错误，从而对集成和Smartsheet应用中的用户体验产生负面影响。为了避免这种情况，在集成设计时，API请求永远不会对同一个Smartsheet对象快速连续执行。为了获得最大效率，可以考虑将更改批处理，并使用支持“批量”的操作在单个请求中提交它们(例如，更新行(年代)或添加列(年代)）.

重点:连续执行请求
我们还强烈建议不要并行执行多个API请求来更新特定的Smartsheet对象。这样做肯定会导致性能下降，并且很可能由于保存碰撞而导致错误。为了避免这种情况，在设计集成时，让更新特定Smartsheet对象的API请求始终是串行执行的(即，每次执行一个请求，直到前一个请求完成后才开始下一个请求)。

聪明:适当地处理错误

一个成功的API请求将导致一个200HTTP状态码，以及响应正文中根据所执行操作的数据。但是如果出了问题你得到的不是200反应?处理能力错误是高质量API集成的关键组件。

如果Smartsheet API请求不成功，API将返回一个4 xx或5 xxHTTP状态码，以及指定发生错误的详细信息的JSON响应体。例如，如果执行得到表请求使用无效的(不存在的)表Id，响应将返回HTTP状态代码404使用以下JSON响应体:

{" errorCode ": 1006， " message ": " Not Found "}

重试还是不重试?

一个成功的错误处理策略要求您的集成能够识别出可以通过重试请求来解决的错误和永远不应该自动重试的错误之间的区别。

的HTTP状态码与响应一起返回的是关于请求结果的第一个指示。

错误处理建议

除了HTTP状态码，您还应该评估smartsheet特定的错误代码对于任何不成功的请求，它都会在响应体中返回。例如:

{" errorCode ": 1006， " message ": " Not Found "}

的API文档为每个smartsheet特定的错误代码指定错误处理建议。我们建议您使用该信息来实现错误处理逻辑，按照以下准则:

• 如果错误代码指示永久错误条件，则不要重试请求。

• 如果错误代码表示可以修复的问题，在问题修复之前不要重试请求。

• 如果错误代码指示可以通过在一段时间后重试请求来克服的问题，请使用指数倒扣．

勤奋:实现日志记录

最后，简要介绍一下日志记录。在理想的情况下，您的集成将从第一天开始无缝运行，并且永远不需要排除任何类型的故障。不幸的是，这种情况很少发生。当出现问题时，重要的是您的集成能够记录API请求和响应。当API问题出现时，访问原始请求和响应(包括详细的错误代码和错误消息)将简化故障排除并加快解决问题的时间。

下面的示例显示了应用程序应该为API请求和响应记录的信息类型。

请求:动词、URI、报头、请求正文

帖子https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
授权:承载MY_TOKEN
内容类型:application / json

请求主体:

[{"title": "FIRST COLUMN \- My New COLUMN "， "index": 0， "type": "TEXT\_NUMBER"}， {"title": "FIRST COLUMN \- My New COLUMN "， "index": 1， "type": "TEXT\_NUMBER"}]

响应:HTTP状态码，响应体

HTTP状态:400坏请求

身体反应:

{"errorCode": 1133， "message": "列标题在输入列中不是唯一的"，"detail": {"columnTitle": "FIRST Column \-我的新列"}}

通常情况下，访问这些信息将使您能够自行识别和解决问题。有时情况并非如此，你会去找api@smartsheet.com如需帮助，我们会要求您提供如上所述的请求/响应信息。因此，从第一天开始就实现API请求和响应日志，可以为自己省去一些麻烦。

最后的话

无论您目前正在设计和构建与Smartsheet的集成，还是之前已经构建了集成，都没有比现在更好的时间来整合我们在这篇文章中介绍的最佳实践:

• 是有效的:使用“bulk”启用的操作

• 是实用的:遵守费率限制准则

• 是聪明的恰当地处理错误

• 勤奋:实现日志记录

充分利用这个机会，通过给予这些因素应有的重视来提高集成的性能、稳定性和可维护性。