README

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

更多信息请参见https://developer.apple.com/weatherkit/get-started/

请注意，Apple 要求在您的代码中使用此 API 时进行归属，详情请参阅https://developer.apple.com/weatherkit/get-started/#attribution-requirements，并且您的 Apple 开发者账户会员资格包括每月高达 500,000 次调用。

安装

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

$ composer require rich2k/laravel-weatherkit

提供者

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

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

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

外观

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

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

配置

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

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

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

身份验证

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

生成密钥文件

如果您想自己生成和管理工作自己的 JWT 令牌，那么您需要首先生成一个 JWT 令牌来访问 WeatherKit API。

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

创建新的 App ID

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

确保您在 功能 和 应用服务 选项卡下都检查了 WeatherKit 选项。点击继续。

创建密钥

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

给密钥起一个名字，例如 WeatherKit，并确保启用 WeatherKit。然后点击继续按钮。然后您将被带到带有注册按钮的页面。

记得下载您最终获得的密钥文件！

所需信息

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

• 您的 Apple 团队 ID
• 您之前创建的 App 包 ID（反向 DNS）。
• 在创建新密钥部分创建的密钥的 Key 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结果

必需

location(lat, lon)

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

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

可选参数

language(lang)

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

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

dataSets([])

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

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

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

// OR

$weather = new \Rich2k\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）。有关更多信息，请参阅许可证文件。