编辑

优化请求

和风天气会根据你的请求，通过API或SDK的方式向你提供天气服务，在这一过程中，需要尽量优化你的请求，以便更高效的使用我们的服务，这篇文档将介绍几种常见的优化方式。

为了更有效的使用和风天气开发服务，你需要尽量优化你的请求。这篇文档将介绍几种常见的优化方式。

构建合法的URL

当你使用API获取数据的时候，会通过URL向我们发起请求，例如：

https://api.qweather.com/v7/weather/3d?parameters

一般来说，这段请求URL不会出现错误，但是在传递一些特殊的参数和值的时候需要特别注意：

不要使用空格

请求链接中不要输入一个空格，这通常发生在复制粘贴的情况下，这种错误可能不会被立即发现，因此需要你在复制粘贴的时候特别注意。

例如: 通常我们会复制粘贴KEY，根据不同的系统或软件，有可能被复制的内容的前后存在空格，当你完成粘贴后，需要将这些空格删除。

使用标准的URI规范字符

你可能需要在API的请求地址中拼接多个参数或值，这些内容会采用特殊符号进行分割，例如坐标的值通过,分割经度和维度，而不要使用中文，

关于标准URI的规范请参考Uniform Resource Identifier (URI): Generic Syntax

URL encoding

对于非ASCII字符集以内的字符，如北京市，你需要对这些字符进行URL encoding

安全的请求

请不要在网页中直接编写URL请求或共享这段URL，这有可能泄露你的敏感信息，使用HTTPS、签名认证等方式可以有效的保护你的敏感信息。关于如果保护KEY及其他发送请求时携带的敏感信息，请参考保护你的KEY。

处理错误

当你遇到返回的数据中code字段的值不是2xx的时候，代表你的请求出现了错误，此时你需要暂停请求并妥善的处理这些错误，否则极端情况下，你可能会违反我们的使用限制而被冻结帐号。

例如: 当你传入了错误的参数或KEY，将返回400或403，此时你应该暂停这一次的请求，排除故障后再继续。否则当产生大量请求错误时，我们可能会冻结你的帐号。

了解状态码

在API/SDK返回的数据中，code字段代表当前请求的状态，返回的值和含义与HTTP Status Code类似，并略有修改。

完整的解释说明请参考状态码。

使用指数退避算法处理错误

当出现错误的时候，请停止请求并进行检查，待故障排除后再恢复请求。然而一些错误并非由于请求不符合规范而导致的，例如超过每分钟请求限制，没有足够的余额等等，这时你应该使用指数退避算法优化请求。

例如，当你的请求收到429状态码时，代表你超过了每分钟请求次数，此时你应该在下次请求开始前添加x秒的等待期。如果下次请求仍然返回429，则将等待期延长一倍，再发送另一次请求，以此类推，继续延长等待期，直至不再返回错误状态码。

简单的公式可以参考：

t = bc

其中t代表下次请求的间隔时间，或称之为等待期，b代表基数，c是发生错误的次数。如果按照上述的例子来讲，假设b = 2，那么在出现第一次错误时，下一次请求应该等待21 = 2秒，再下一次请求应等待22 = 4秒，第三次请求等待23 = 8秒，如果第四次请求响应正常，则恢复之前的请求频率并重置c = 1。

避免冲突

如果你有大量独立设备发送请求，为了避免这些设备产生了相同的等待期而产生冲突（比如都在等待2秒后重新发送，这并不能恢复QPM），你可以在等待期中设置一个随机数，或称之为插槽，这个随机数的取值范围可以是0～2c-1。在上述例子中，前三次的等待期的随机数分别是：

  • 第一次：0, 1
  • 第二次：0, 1, 2, 3
  • 第三次：0, 1, 2, 3, 4, 5, 6, 7

这样你的多个独立设备每次都有不同的等待期而避免了冲突。

截断

等待期不应是无限的，如果连续出现20次错误，那么此时的等待期就已经长达291个小时，这显然是不现实的。因此你需要为等待期设置一个最大值，当达到这个值时，则不再增加c的取值。我们的建议是c = 10。

按需请求

仅在需要天气数据的时候再进行请求。

例如：在APP中，天气内容的位置较为靠下，你可以让程序在用户滑动到天气内容部分再进行请求。

如果已经加载了天气内容，你也可以为这个内容设置缓存时间，或者增加一个刷新按钮，让用户手动去刷新数据。关于设置缓存，请参考缓存你的数据。