README

⚠️ 免责声明 ⚠️

Apple 的 WeatherKit REST API 目前仍在测试版，文档尚未完全更新。

在开发过程中遇到了未记录的响应和值，但已尽力根据当时可用的信息进行处理。

📖 目录

特性
安装
- Laravel 提供商
认证
- 创建新的 App ID
- 创建新的密钥
用法
文档
许可证

🚀 特性

多种预报类型
- 当前天气
- 下一小时（分钟级）预报 🔹
- 每小时预报
- 每日预报
天气警报 🔸
内置单位转换
- 长度
- 压力
- 速度
- 温度

🔹 = 在支持的国家/地区可用。 🔸 = 当提供国家/地区代码时。

📦 安装

您可以通过以下命令使用 Composer 安装此包

composer require rugaard/weatherkit

Laravel 提供商

此包包含适用于 Laravel 框架的现成服务提供商。如果您正在使用 Laravel 的新版本（>= 5.5），则服务提供商将自动加载。

如果您使用的是旧版本，则需要手动将服务提供商添加到 config/app.php 文件中

'providers' => [
    Rugaard\WeatherKit\Providers\LaravelServiceProvider::class,
]

配置

默认包配置已设置为使用以下环境变量。

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

php artisan vendor:publish --provider=\Rugaard\WeatherKit\Providers\LaravelServiceProvider

🔑 认证

在 Apple 收购了 DarkSky 并将其转变为 WeatherKit 之后，API 现在需要认证。为了能够进行认证，您必须是 Apple 开发者计划的成员。

一旦您注册了 Apple 开发者计划，您必须注册一个新的 App ID 并创建一个新的密钥。

创建新的 App ID

要创建一个新的 App ID，您必须在此表单上注册您的应用程序。输入简短描述并为您应用程序提供一个唯一的包标识符（反向 URL）。

示例

填写完所有必填字段后，您需要在功能和 应用服务 标签下选择 ☑️ WeatherKit。

然后，点击蓝色按钮继续，您就完成了。

创建新的密钥

要创建一个新的密钥，您必须从此表单生成它。

为您的密钥命名并确保启用 ☑️ WeatherKit。完成后，点击蓝色按钮继续。您将被重定向到一个确认页面，在该页面上点击蓝色按钮注册。

然后，将您的密钥作为物理文件下载到您的计算机上。它用于与 API 进行认证。

就这样，您完成了。

⚙️ 用法

在客户端实例化之前，需要访问令牌。为了生成访问令牌，苹果要求您创建一个App ID和密钥，并将其下载为物理文件。

如果您还没有完成这些操作，可以按照README中的🔑“认证”部分的指南进行操作。

生成访问令牌

要生成访问令牌，您需要以下几样东西

在创建新App ID部分中创建的App ID前缀和Bundle ID。
在创建新密钥部分中创建的密钥的Key ID。
在创建新密钥部分中下载的物理密钥。

<?php

use Rugaard\WeatherKit\Token;

// Details from "Create new App ID" section.
$appIdPrefix = 'O9876S4E2I';
$bundleId = 'com.forecast.weather';

// Details from "Create new key" section.
$pathToKey = 'credentials/AuthKey_I2E4S6789O.p8'
$keyId = 1234567890;

// Create Token instance.
$token = new Token($pathToKey, $keyId, $appIdPrefix, $bundleId);

创建一个Token实例后，您可以通过两种不同的方式检索生成的访问令牌。

// Method 1: getToken()
$accessToken = $token->getToken();

// Method 2: __toString()
$accessToken = (string) $token;

独立

在我们能够向API发送请求之前，我们需要实例化HTTP客户端。客户端可以带默认位置或不带默认位置进行实例化。

<?php

use Rugaard\WeatherKit\Client;

// Instantiate client without default location.
$weatherKit = new Client($token->getToken(), null, null, null);

// Instantiate client with default location.
$weatherKit = new Client((string) $token, 55.6736841, 12.5681471, 'dk');

// Instantiate client with default location and local language/timezone.
$weatherKit = new Client((string) $token, 55.6736841, 12.5681471, 'dk', 'da', 'Europe/Copenhagen');

当客户端实例化后，如果需要，可以更改位置、语言和时区。

// Change location to London.
$weatherKit->setLocation(51.5286416, -0.1015987);

// Country code is optional
// but required to retrieve weather alerts.
$weatherKit->setLocation(51.5286416, -0.1015987, 'gb');

// Change language to German.
$weatherKit->setLanguage('de');

// Change timezone to Paris.
$weatherKit->setTimezone('Europe/Paris');

您可以一次性检索所有预报，也可以单独检索。

// Get all forecasts at once.
/* @var $forecasts \Illuminate\Support\Collection */
$forecasts = $weatherKit->weather();

// Get current forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Currently */
$forecast = $weatherKit->currently();

// Get next hour (minute-by-minute) forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\NextHour */
$forecast = $weatherKit->nextHour();

// Get hourly forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Hourly */
$forecast = $weatherKit->hourly();

// Get daily forecast.
/* @var $forecast \Rugaard\WeatherKit\DTO\DataSets\Daily */
$forecast = $weatherKit->daily();

当客户端设置了国家代码后，如果位置有相关的天气警报，您将能够检索到天气警报。

// Get weather alerts.
/* @var $alerts \Rugaard\WeatherKit\DTO\DataSets\Alerts */
$alerts = $weatherKit->alerts();

// Get detailed information about a specific alert.
/* @var $alertDetails \Rugaard\WeatherKit\DTO\Forecasts\AlertDetails */
$alertDetails = $weatherKit->alert($alerts->getData()->first()->getId());

与 Laravel 一起使用

当与Laravel一起使用此包时，客户端将自动实例化并添加到服务容器中。

默认情况下，设置通过环境变量进行，具体在📦 安装部分中描述。如果您想使用其他方法，可以在config/weatherkit.php配置文件中更改。

<?php

namespace App\Http\Controllers;

use Illuminate\Routing\Controller;
use Rugaard\WeatherKit\Client as WeatherKit;

class WeatherController extends Controller
{
    /**
     * Get all forecasts at once.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function forecast(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->weather();
    }
    
    /**
     * Get current weather measurements.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function currently(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->currently();
    }
    
    /**
     * Get next hour (minute-by-minute) forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function nextHour(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->nextHour();
    }
    
    /**
     * Get hourly forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function hourly(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->hourly();
    }
    
    /**
     * Get daily forecast.
     *
     * @param \Rugaard\WeatherKit\Client $weatherKit
     */
    public function daily(WeatherKit $weatherKit)
    {
        $forecasts = $weatherKit->setLocation(55.6736841, 12.5681471, 'dk')->daily();
    }
}

您可以通过在AppServiceProvider的boot()方法中设置默认设置来设置/更改Client的默认设置。这样，您可以避免在每个请求上设置位置/语言/时区。

<?php

namespace App\Providers;

use Illuminate\Support\ServiceProvider;
use Rugaard\WeatherKit\Client as WeatherKit;

class AppServiceProvider extends ServiceProvider
{
    /**
     * Register any application services.
     *
     * @return void
     */
    public function register()
    {
        //
    }

    /**
     * Bootstrap any application services.
     *
     * @return void
     */
    public function boot(WeatherKit $weatherKit)
    {
        // Change location to London.
        $weatherKit->setLocation(51.5286416, -0.1015987);
        
        // Country code is optional
        // but required to retrieve weather alerts.
        $weatherKit->setLocation(51.5286416, -0.1015987, 'gb');
        
        // Change language to German.
        $weatherKit->setLanguage('de');
        
        // Change timezone to Paris.
        $weatherKit->setTimezone('Europe/Paris');
    }
}

📚 文档

有关预报类型、测量等更深入的文档，请参阅Wiki。

🚓 许可证

此包根据MIT许可。

由于此包使用苹果服务，您需要遵循苹果天气数据的归属指南和要求。更多详情，请查看苹果网站上的归属要求。

rugard / weatherkit

维护者

详细信息