在设计和构建API集成时，很容易过于关注操作、属性和参数的细节，而忽略了可能显著影响集成的性能、稳定性和维护的因素。
给予这些因素应有的重视可能意味着一个不可靠的集成和一个坚如磐石的集成之间的区别。为了确保您的集成是最好的，我们强烈建议结合以下四个Smartsheet API最佳实践:
1.高效:使用“批量”支持的操作
为了提高效率，尽可能使用支持大容量的API操作。支持大容量的API操作允许您使用单个API请求添加、更新或删除多个项。
例如，如果需要更新工作表中的10行，则使用单个行更新的行请求，而不是执行10个单独的请求(每行一个)。
支持大容量的操作通过大幅减少集成必须执行的出站调用的数量来提高效率。这降低了你击中速率限制(因为每个批量操作只计算为一个请求的限制)。
以下API操作目前允许您批量完成以下任务:
我们将在未来增加更多的“批量”操作，所以要注意那些额外的机会来提高效率。记住，最好的做法是尽可能地批量处理事情。
小贴士:允许部分成功
通常，当在批量操作期间抛出错误时，默认行为是让整个操作失败。例如，如果您向Update Rows发出请求，而请求中的一个行对象无效，则整个操作将失败，任何行都不会更新。
但是，您可以选择允许部分成功在大部分的请求。允许部分成功将允许执行请求的成功部分，即使在操作期间抛出了错误。
2.实际一点:遵守费率限制准则
处理“速率限制超过”错误
Smartsheet API目前强加了一个速率限制每个访问令牌每分钟300个请求。
某些资源密集型操作，例如附加文件或让细胞的历史，作为速率限制中的10个请求。如果超出这个速率限制，后续的API请求(在一分钟内)将返回一个429 HTTP状态码，以及以下JSON响应体:
｛
“错误代码”:4003年,
"消息":"超出速率限制。"
｝
我们建议您设计您的集成来优雅地处理这个速率限制错误。实现这一点的一种方法是，在遇到错误时让集成休眠60秒，然后重试请求。
或者，您可以选择实现指数回退，这是一种错误处理策略，通过这种策略，您定期重试失败的请求，重试之间的等待时间逐渐变长，直到请求成功或达到一定的重试尝试次数。
避免执行“快速”更新
此外，我们强烈建议您避免在非常短的时间内一次又一次地执行API请求来更新特定的Smartsheet对象。
例如，如果您的集成所做的唯一事情是每秒钟对同一个表执行一次Update Rows请求，那么总共每分钟只执行60个请求—完全在速率限制准则内。
然而，如此快速地连续更新同一个对象可能会导致保存错误，这会对集成和Smartsheet平台中的用户体验产生负面影响。
为了避免这种情况，设计您的集成，使API请求永远不会快速连续地针对同一个Smartsheet对象执行。为了提高效率，可以考虑批量处理更改，并使用支持“批量”的操作(例如更新行或添加列)在单个请求中提交它们。
连续执行请求的
我们还强烈建议不要同时执行多个API请求来更新特定的Smartsheet对象。这样做将导致性能降低，并极有可能导致由于保存冲突而产生的错误。
为了避免这种情况，在设计您的集成时，应该始终串行执行更新特定Smartsheet对象的API请求:每次执行一个请求，直到前一个请求完成才开始下一个请求。
3.聪明:适当地处理错误
一个成功的API请求将导致一个200的HTTP状态码，以及根据执行的操作在响应体中的数据。但是，如果出现了错误，而您得到的不是200个响应，会发生什么呢?适当处理错误的能力是高质量API集成的关键组成部分。
如果Smartsheet API请求不成功，该API将返回4xx或5xx HTTP状态码，以及指定发生错误详细信息的JSON响应体。例如，如果您执行得到表请求使用一个无效的(不存在的)表Id，响应将返回一个HTTP状态代码404和以下JSON响应体:
｛
“错误代码”:1006年,
“消息”:“找不到”
｝
什么时候重试?
一个成功的错误处理策略要求集成识别可以通过重试请求解决的错误和永远不应该自动重试的错误之间的区别。
的HTTP状态代码与响应一起返回的是关于请求结果的第一个指示。
错误处理建议
除了HTTP状态代码，您还应该评估特定于smartsheet的错误代码它将在任何不成功的请求的响应体中返回。例如:
｛
“错误代码”:1006年,
“消息”:“找不到”
｝
API文档为每个特定于smartsheet的错误代码指定了错误处理建议。我们建议您使用该信息来根据以下指导原则实现错误处理逻辑:
如果错误代码指示永久错误条件，则不要重试请求。
如果错误代码指示可以修复的问题，在问题修复之前不要重试请求。
如果错误代码指示可以在一段时间后重试请求来克服的问题，则使用指数回退重试请求。
4.勤奋:实现日志记录
在理想的情况下，您的集成从第一天起就可以无缝地运行，并且永远不需要排除任何类型的问题。
不幸的是，这种情况很少发生。当出现问题时，重要的是您的集成能够记录API请求和响应。
当API问题出现时，访问原始请求和响应(包括详细的错误代码和错误消息)将简化故障排除并加快解决问题的时间。
以下示例显示了应用程序应该记录API请求和响应的信息类型:
请求:动词、URI、标头、请求主体
文章https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
授权:无记名MY_TOKEN
内容类型:application / json
请求主体:
［
｛
"标题":"第一栏-我的新专栏"，
“指数”:0,
“类型”:“TEXT_NUMBER”
}，
｛
"标题":"第一栏-我的新专栏"，
“指数”:1、
“类型”:“TEXT_NUMBER”
｝
］
响应:HTTP状态码，响应体
HTTP状态:400错误请求
身体反应:
｛
“错误代码”:1133年,
"message": "列标题在输入列中不是唯一的。"
"细节":{
"columnTitle": "FIRST COLUMN -我的新专栏"
｝
｝
通常情况下，访问这些信息将使您能够自行识别和解决问题。如果情况并非如此，您可以访问devrel@smartsheet.com寻求帮助。为了排除故障，我们将要求您提供上述请求/响应信息。
您应该在第一次设置集成时实现API请求和响应日志记录，因为这将使体验更有效地运行。
开始构建您的集成
无论您目前正在设计和构建与Smartsheet的集成，还是以前已经构建了集成，都没有比现在更好的时机来整合我们在本文中介绍的最佳实践。
此外，我们鼓励您充分利用内容开发人员门户获取本文欧宝体育app官方888讨论的资源和指导，所有这些都旨在帮助您加快使用Smartsheet API所需的时间，帮助您自信地部署您的解决方案。
订阅内容是通讯以帮助IT专业人员增加他们对业务的影响的技巧、策略和想法。
