LinkyAPI 1.0.4

LinkyAPI 1.0.4

×

由 Karim Angama 维护。

LinkyAPI 1.0.4

iOS-LinkyAPI

LinkyAPI Swift 库是一个 Swift 包，它提供了一种方便的方式来通过 Enedis API 获取 Linky 的电力消耗和生产数据。这个库简化了获取用户授权和检索消费数据的过程。

功能

  • API 授权流程。
  • 检索每日消耗量、平均耗电量、最大耗电功率、每日产量和平均产电量。
  • 结构化的 Swift API，便于集成到您的 iOS 应用程序中。

要求

LinkyAPI 需要：

  • Xcode 14+
  • Swift 5.0+
  • iOS 16.4+

安装

要使用 CocoaPods 安装此框架，请将以下行添加到您的 Podfile 中：

pod 'LinkyAPI'

然后在终端中运行 pod install。

开始之前

开发者账号和应用注册

在将 Linky API 库集成到您的 Swift 应用程序之前，需要完成几个初步步骤。您需要创建一个 Enedis 的开发者账号。在此过程中，您将获得必要的凭证，包括客户 ID 和客户密钥。此外，您必须为 Linky API 的使用注册一个特定应用。此注册通常要求提供有效的 SIRET 编号，并与 Enedis 签订合同协议。

有关更多信息以及访问 Enedis，请访问 Enedis DataHub。

库集成

一旦您的开发者账号激活，并且签署了必要合同，您就可以将 Linky API 库集成到您的 Swift 应用程序中。该库提供了方便的结构和类，例如 LinkyConfiguration 用于设置 API 访问参数和 LinkyAuthorization 用于处理授权流程。

重要：应用程序必须在“沙箱”模式下开发和实施符合要求的客户旅程后，才能访问真实数据。

过渡到生产模式

在完成初始设置后，您可以在“沙箱”模式下使用 Linky API，但要过渡到生产模式，需要额外步骤。具体来说，您需要向 Enedis 提交请求以在 production 中激活。一旦批准，您可以从“沙箱”无缝切换到 production 模式，从而使您的应用程序能够访问真实用户数据。

使用

授权

要授权访问 Linky API，您需要使用您的客户 ID、客户密钥和其他必需参数创建一个 LinkyConfiguration 实例。然后，使用 LinkyAuthorization 类启动授权流程。

let configuration = LinkyConfiguration(
    clientId: "your_client_id",
    clientSecret: "your_client_secret",
    redirectURI: URL(string: "your_redirect_uri")!,
    mode: .sandbox(prm: .client0),
    duration: .day(value: 1)
)
let linkyAuth = LinkyAuthorization(configuration: configuration)

// Launch the authorization request
linkyAuth.authorization { error in
    if error == nil {
        // Authorization successful, proceed with data retrieval
    } else {
        // Handle authorization error
    }
}

沙箱模式

“沙箱”模式用于开发和测试目的。在此模式下，您可以使用特定的配送点，称为 PRM（测量参考点）来模拟电力消耗和生产数据。这些 PRM 代表不同的场景，例如具有特定消耗模式的客户。

在您的实现中，“沙箱”模式使用 LinkyMode 结构和 .sandbox 变体配置，指定特定的 PRM。例如

let configuration = LinkyConfiguration(
    ...
    mode: .sandbox(prm: .client0), // Using PRM client0 to simulate specific data
    ...
)

生产模式

“生产”模式用于您的应用程序准备通过 Enedis 网络从最终用户那里获取真实消耗和生产电力数据时。在此模式下，检索的数据是真实的，反映了生产中的 Linky 电表的指标。

要将您的实现切换到“生产”模式，请使用 LinkyMode 结构体中的 .production 变体

let configuration = LinkyConfiguration(
    ...
    mode: .sandbox(prm: .production),
    ...
)

当过渡到“生产”模式时，请确保您的应用程序准备好处理真实数据，并符合所有数据保护和隐私法规。

同意请求的时长

LinkyConfiguration 结构体中的 duration 参数表示应用程序在授权访问 Linky API 时请求的同意时长。此时长将在授权过程中显示给最终用户。用户必须明确、知情地同意指定时长。

let configuration = LinkyConfiguration(
    ...
    duration: .day(value: 1)
    ...
)

时长参数的类型是 LinkyDuration，它是一个表示不同时长的枚举。可用的选项有

  • 日：请求特定天数内的同意。
LinkyDuration.day(value: 7) // Request consent for 7 days
  • 月：请求特定月数内的同意。
LinkyDuration.month(value: 2) // Request consent for 2 months
  • 年：请求特定年数内的同意。
LinkyDuration.year(value: 3) // Request consent for 3 years

生产环境的重定向 URI

redirectURI 参数在生产环境中至关重要。它是在请求启用您的开发者帐户时需要指定的 URL。Enedis 认证后可选择生产模式。

let configuration = LinkyConfiguration(
    ...
    redirectURI: URL(string: "your_production_redirect_uri")!,
    ...
)

数据检索

一旦获得授权，您可以使用 LinkyConsumption 结构体检索各种消费和生产数据。

// Retrieve daily consumption
LinkyConsumption.shared.daily(start: startDate, end: endDate) { consumption, error in
    if let consumption = consumption {
        // Handle daily consumption data
    } else {
        // Handle error
    }
}

// Retrieve average power consumed over a 30 min interval
LinkyConsumption.shared.loadcurve(start: startDate, end: endDate) { consumption, error in
    if let consumption = consumption {
        // Handle load curve data
    } else {
        // Handle error
    }
}
// Other data retrieval methods are available

贡献力量

LinkyAPI 欢迎贡献力量！如果您发现任何问题或对改进有建议，请随时提出问题或提交拉取请求。

作者

k-angama, [email protected]

许可

LinkyAPI 在 MIT 许可下提供。有关更多信息，请参阅 LICENSE 文件。