README

这提供了一个用于Apple的WeatherKit API的Laravel风格的包装器，该API取代了DarkSky API。

有关更多信息，请参阅https://developer.apple.com/weatherkit/get-started/

请注意，Apple要求在您的代码中使用此API时进行归属，有关归属要求，请参阅https://developer.apple.com/weatherkit/get-started/#attribution-requirements，并且每月包含高达50万个调用次数，这些调用次数包含在您的Apple开发者账户会员资格中。

安装

使用以下命令通过composer安装此包：

$ composer require mobiadroit/laravel-weatherkit

提供者

此库与Laravel的Service Providers无缝工作，将在Laravel >= 5.5中自动加载。

当然，如果您愿意，可以手动将其添加到您的config/app.php文件中的providers数组中。

'providers' => [
    Mobiadroit\LaravelWeatherKit\Providers\LaravelServiceProvider::class,
]

外观

要将外观访问器注册到config/app.php中的aliases数组中，请添加以下内容：

'aliases' => [
    'WeatherKit' => Mobiadroit\LaravelWeatherKit\Facades\WeatherKit::class,
]

配置

有关如何使用这些环境变量的说明，请参阅身份验证部分。

如果您想更改默认配置，可以将配置文件发布到您的项目中。

$ php artisan vendor:publish --provider=\Mobiadroit\LaravelWeatherKit\Providers\LaravelServiceProvider

身份验证

使用此库与WeatherKit进行身份验证有两种方式。您需要首先为选择的方法生成密钥文件。

生成密钥文件

如果您想自己生成和管理JWT令牌，那么您需要首先生成JWT令牌以访问WeatherKit API。

您需要注册付费的Apple开发者计划，并在开发者账户中注册新的App ID并创建密钥。

创建新的App ID

在账户的标识符部分创建App标识符。输入简短描述，并为您的应用程序提供一个唯一的包ID（例如，com.myapp.weather）。

确保在“能力”和“应用程序服务”选项卡下都勾选了WeatherKit。然后点击继续。

创建密钥

转到您的开发者账户中的密钥页面。

为密钥命名，例如WeatherKit，并确保启用WeatherKit。然后点击继续按钮。然后您将进入一个带有注册按钮的页面。

请记住下载您最终得到的密钥文件！

所需信息

无论您决定使用哪种身份验证方法，我们首先需要一些额外的信息。

• 您的Apple团队ID
• 您之前创建的应用程序包ID（反向DNS）。
• 您在创建新密钥部分创建的密钥ID，您可以在生成后任何时候获取此信息。
• 您下载的以.p8结尾的物理密钥文件。

手动JWT令牌生成

一旦您生成了上面的.p8密钥文件，我们现在需要生成您的JWT令牌和公钥/私钥。

使用openssl创建您的私钥，格式为PEM

openssl pkcs8 -nocrypt -in AuthKey_ABC1235XS.p8 -out AuthKey_ABC1235XS.pem

注意：选项-nocrypt是必需的！

还需要公钥来签署JWT令牌

openssl ec -in AuthKey_ABC1235XS.pem -pubout > AuthKey_ABC1235XS.pub

现在你应该有两个文件，一个是公钥，另一个是私钥。这些将用于签名你的JWT令牌。

使用JWT令牌生成器，例如 https://jwt.net.cn/

对于你想要的报头

{
  "alg": "ES256",
  "kid": "<Your 10 digit WeatherKit Key ID>",
  "id": "<Apple Team ID>.<App Identifier>"
}

有效载荷

{
  "iss": "<Apple Team ID>",
  "iat": <Unix Timestamp Now>,
  "exp": <Unix Timestamp to Expire Key>,
  "sub": "<App Identifier>"
}

例如。

{
  "alg": "ES256",
  "kid": "ABC1234567",
  "id": "DEV1234567.com.myapp.weather"
},
{
  "iss": "DEV1234567",
  "iat": 1670851291,
  "exp": 1702385664,
  "sub": "com.myapp.weather"
}

将你的私钥和公钥复制并粘贴到签名验证中，输出就是你需要添加到配置 WEATHERKIT_JWT_TOKEN 中的内容。

配置

将以下行添加到 .env 文件中

WEATHERKIT_AUTH_TYPE=jwt
WEATHERKIT_JWT_TOKEN=<your_weatherkit_jwt_token>

动态令牌生成

从库版本 >=1.2 开始，你可以直接动态生成JWT令牌。

配置

将以下行添加到 .env 文件中

WEATHERKIT_AUTH_TYPE=p8
WEATHERKIT_KEY=<Path To Key File/Key String>
WEATHERKIT_KEY_ID=<Key Id>
WEATHERKIT_TEAM_ID=<Team Id>
WEATHERKIT_BUNDLE_ID=<Bundle ID>

用法

有关响应格式的详细信息，请访问： https://developer.apple.com/documentation/weatherkitrestapi/get_api_v1_weather_language_latitude_longitude

目前有两个端点可用，即可用性和天气。

可用性允许你检索给定位置可用的数据集。如果你在调用天气函数之前调用可用性函数，我们将自动将请求的数据集设置为可用。

availability() 和 weather() 函数将它们的结果作为Laravel Collection 返回

必需

位置(lat, lon)

传入纬度和经度坐标以获取基本响应

WeatherKit::location(lat, lon)->weather();

可选参数

语言(lang)

传入语言代码以返回基于请求语言的文本响应。默认为 en_US

WeatherKit::lang('en_GB')->location(lat, lon)->weather();

数据集([])

指定要使用的数据集以减少数据传输。

默认情况下，我们将尝试调用 'currentWeather', 'forecastDaily', 'forecastHourly', 'forecastNextHour'，但是你可以使用 dataSets() 函数手动设置这些参数。你也可以在通过外观调用之前，在调用 weather() 之前调用 availability() 来动态设置这些参数。

WeatherKit::location(lat, lon)->dataSets(['currentWeather', 'forecastDaily'])->weather();

// OR

$weather = new \Mobiadroit\LaravelWeatherKit\WeatherKit();
$weather->location(lat, lon)->availability();
$weather->location(lat, lon)->weather();

currentAsOf(t)

传入时间对象的Carbon对象以获取当前条件。默认为现在。

WeatherKit::location(lat, lon)->currentAsOf(now())->weather();

dailyStart(t)/dailyEnd(t)

dailyStart()：每日预报开始的时间。如果此参数不存在，则每日预报从当天开始。dailyEnd()：每日预报结束的时间。如果此参数不存在，则每日预报持续10天。

WeatherKit::location(lat, lon)->dailyStart(now()->subDays(7))->dailyEnd(now())->weather();

hourlyStart(t)/hourlyEnd(t)

hourlyStart()：开始每小时预报的时间。如果此参数不存在，则每小时预报从当前小时开始。hourlyEnd()：结束每小时预报的时间。如果此参数不存在，则每小时预报持续24小时或每日预报的长度，以较长者为准。

WeatherKit::location(lat, lon)->hourlyStart(now()->subHours(24))->hourlyEnd(now())->weather();

timezone(timezone)

要用于将天气预报汇总为每日预报的时间区域名称。默认为未设置，因为这不是必需的，除非调用每日预报。

WeatherKit::location(lat, lon)->timezone('Americas/Los_Angeles')->weather();

辅助函数

以下是一些简写辅助函数，用于增加可读性，相当于将 dataSets 设置为单个对象。

->currently()
->hourly()
->daily()
->nextHour()

例如，这两个语句是相同的

WeatherKit::location(lat, lon)->hourly()
WeatherKit::location(lat, lon)->dataSets(['forecastHourly'])->weather()->get('forecastHourly')

许可

MIT许可（MIT）。有关更多信息，请参阅 许可文件