Windows 10 中的移动运营商帐户管理

2025-07-18

本主题介绍 Windows 提供的移动运营商帐户管理体验，可以使用移动计划进行扩展。

基本帐户管理体验

本部分介绍用于配置 Windows 连接管理器中显示的 “查看我的帐户 ”链接（也称为网络浮出控件）的选项。

可以将“ 查看我的帐户 ”链接配置为：

启动 Web 浏览器并打开定义的网页。
启动移动应用并打开移动运营商 Web 门户。

确定上述选项之一后，请请求 COSA 数据库更新来实现正确的行为。有关详细信息，请参阅桌面 COSA 数据库提交规划。

以下设置适用于上述选项：

AccountExperienceURL。此参数定义网页。
AppID。此参数定义启动的应用。若要使用移动套餐应用，请配置 Microsoft.OneConnect_8wekyb3d8bbwe!App。

下图显示了网络弹出窗口的示例：

增强的帐户管理体验

通过实现增强的帐户管理体验，你可以为客户提供以下优势：

客户可以在网络浮出控件中查看可用数据量，以及订阅到期前所剩的时间。
客户可以通过移动连接来充值预付费订阅，即使他们用完预付费余额或订阅已过期也是如此。
可以根据客户的订阅状态管理您的网络弹出服务。

这些体验建立在基本帐户管理体验的基础上，这是设备网络浮出控件中的默认体验。

根据从 GetBalance API 调用接收的信息，网络浮出控件的行为方式不同，从而提高用户体验。

网络浮出面板具有以下元素：

使用数据计划进行连接。这会启动移动套餐应用程序。
查看我的帐户。基于基本帐户管理体验的行为。
平衡信息。显示可用余额，该余额在您的 GetBalance 响应中提供。

下图显示了这些网络浮出控件元素。使用数据计划进行连接对应于 A，查看我的帐户对应于 B，余额信息对应于 C。

Windows 连接管理器显示行为，具体取决于 GetBalance API 调用

若要在网络浮出控件中提供正确的信息，MO 提供 GetBalance API 部分中定义的 Type 和 Balance（dataRemainingMB 和 timeRemaining）信息。

下表提供 GetBalance 响应类型和网络浮出控件显示内容之间的参考对照。

GetBalance 响应类型	网络弹出菜单显示...
MODIRECT	“查看我的帐户”仅没有余额信息
MODIRECTPAYG	“查看我的帐户”和余额信息
没有	“使用流量套餐进行连接”
不支持	“仅查看我的帐户”

GetBalance API

重要

请请求 Windows COSA 更新以在 Windows 中启用 Get Balance 。

GetBalance API 查询当前订阅状态，控制移动设备计划体验是否在设备上可用，并在预付费订阅的网络浮出控件中显示剩余的数据和时间。下图显示了 GetBalance API 的高级流程。

资源模型

移动套餐服务与移动运营商 API 之间的通信涉及操作以下示意图中的资源。关系图后面的表中列出了每个资源的说明。

SIM 资源

注释

SIM 资源目前不支持“创建”、“读取”、“更新”或“删除”作。

JSON 属性	类型	DESCRIPTION
Iccid	字符串	已创建的配置文件的 ICCID。

平衡资源

JSON 属性	类型	DESCRIPTION
id	字符串	移动运营商内部 ID，用于跟踪事务
类型	枚举	可能的值： MODIRECT：指示用户余额是否为 MO Direct。 MODIRECTPAYG：指示用户余额是否为 MO Direct PAYG。 NONE：表示用户没有余额。当剩余余额为 0 但计划尚未过期时，我们预期会收到“NONE”，以便用户可以购买数据计划。 NOTSUPPORTED：指示移动计划体验不支持 SIM 卡。当 SIM 卡不应位于*移动计划支持的范围内时，将使用“NOTSUPPORTED”。当我们收到此类型时，我们将在网络弹出框中关闭移动计划功能，并在移动计划应用中返回一般错误消息。
剩余数据量_MB	加倍	当前用户计划中剩余的数据（以 MB 为单位）。
剩余时间	字符串	ISO 8601 中指定的持续时间。

标头

以下标头可以包含在从移动计划服务到移动提供商终结点的每个请求中。

标题名称	价值	DESCRIPTION
X-MS-DM-TransactionId	字符串	用于唯一标识移动计划服务与 MO 服务之间的请求/响应交互的 TransactionId。
授权（可选）	字符串	可选由 MO 提供的基本身份验证字符串。

错误代码

下表定义了应在 HTTP 响应中使用的错误代码。

错误代码	DESCRIPTION
HTTP 200 （成功）	作已成功完成。此代码还应该用于指示用户在指定位置是否具有 0 个余额，这应该使用 dataRemainingInMB=0 和 timeRemaining=“PT0S”和 HTTP 200 来完成。
HTTP 201 （已创建）	指示操作已成功完成，并且资源已成功创建。
HTTP 400 （错误请求）	针对无效的查询参数、无效的标头或无效的数据负载。在响应正文中，应指示不正确的参数。例如，如果指定了无效的 fieldsTemplate，则必须返回此错误代码，并在响应正文中包含详细信息。
HTTP 401 （未授权）	身份验证凭据不正确或无效。当传递的基本身份验证凭据不正确时，可能会发生这种情况。
HTTP 403 （禁止）	客户端证书不受信任或无效。如果作为 MTLS 的一部分包含的客户端证书无效，应返回 HTTP 403。
HTTP 404 （找不到）	如果资源不存在，MO 服务应返回此错误。发送错误的 ICCID 时，可能会发生这种情况。不应使用此方法指示用户在指定位置没有余额，而应该用 HTTP 200 （OK）来表示。
HTTP 409 （冲突）	用于 TransactionId 重复的情况。
HTTP 429（请求过多）	MO 服务用于指示移动套餐服务在指定时间内发送的请求过多。在响应中，MO 服务必须使用 Retry-After 标头来指示移动套餐服务应在何时重试获取该资源。在响应正文中，可以提供可选详细信息。
HTTP 500 （内部错误）	MO 服务发生意外情况。 MO 服务应尽可能包含错误原因，以便根据需要将其用于进一步调试。

GetBalance API 规范

当 GetBalance 网络浮出控件显示在 Windows 设备中时，将调用该 API。移动计划服务是此通信的代理。

此调用是通过 HTTP 请求完成的，其中 moBaseUrl 是 MO 托管服务的终结点， sim ID 是 ICCID：

GET https://{moBaseUrl}/sims/{sim id}/balances?fieldsTemplate=basic&limit=1&location=US HTTP/1.1

查询参数：

查询参数名称	价值	DESCRIPTION
位置	字符串	可选。查询用户余额的地点。如果未指定，则预期所有活动余额。注意位置参数区分大小写。
限制	整数	可选。要返回余额的最大数量。如果未指定，则应返回所有余额。
fieldsTemplate	枚举	指定必须在资源中返回的字段列表。可能的值：基本：必须返回 Balance 资源中的 type、 dataRemainingInMB 和 timeRemaining 。完整：必须返回平衡资源中的所有属性。

查询参数名称

价值

DESCRIPTION

位置

字符串

可选。查询用户余额的地点。如果未指定，则预期所有活动余额。注意位置参数区分大小写。

限制

整数

可选。要返回余额的最大数量。如果未指定，则应返回所有余额。

fieldsTemplate

枚举

指定必须在资源中返回的字段列表。

可能的值：

基本：必须返回 Balance 资源中的 type、 dataRemainingInMB 和 timeRemaining 。
完整：必须返回平衡资源中的所有属性。

以下一系列示例显示了 API 的 GetBalance 调用流。

示例 1：返回美国用户可用的第一个余额

GET https://moendpoint.com/v1/sims/iccid: 8988247000100003319/balances?fieldsTemplate=basic&limit=1&location=us HTTP/1.1
X-MS-DM-TransactionId: “MSFT-12345678-1234-1234-1234-123456789abc”

HTTP 响应：

HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: “12345”

{
“balances”: [
    {
         “id”: “23445”,
         “type”: “MODIRECTPAYG”,
         “dataRemaininginMB”: 123.0,
         “timeRemaining”: “P23DT23H”
    }
  ]
}

如果成功，此方法将返回用户的余额。

响应 JSON：

数据	类型	DESCRIPTION
Balances	收集	余额集合。

示例 2：在 COSA ICCID 范围内但移动套餐不应支持的 SIM 卡的预期响应

HTTP 请求：

GET https://{moBaseUrl}/sims/{sim id}/balances?fieldsTemplate=basic&limit=1&location=US
HTTP/1.1

响应 JSON：

HTTP/1.1 200 OK
Content-type: application/json
X-MS-DM-TransactionId: “12345”

{
“balances”: [
    {
         “id”: “23445”,
         “type”: “NOTSUPPORTED”,
         “dataRemaininginMB”: 0.0,
         “timeRemaining”: “PT0S”
    }
  ]
}

身份验证

移动计划服务和移动运营商 API 之间的通信是通过基于证书的客户端身份验证执行的。

在调用移动运营商 API 期间，将传递具有以下主题名称的证书：

C=US, ST=WA, L=Redmond, O=Microsoft Corporation, CN=partners.datamart.windows.com

证书链至此 CA： DigiCert 全局根证书 G2。

建议所有移动运营商验证证书的使用者名称是否与上述名称匹配。

如何在 Windows COSA 中启用 Get Balance

需要在 Windows COSA 数据库中配置以下设置，以便在 Windows 设备上启用 Get Balance 支持。

需要以下 COSA 设置：

SupportDataMarketplace （必须设置为“是”）
DataMarketplaceRoamingUIEnabled
SIM ICCID 范围（ICCID 范围 – 开始和 ICCID 范围 – 结束）

有关所有受支持字段的详细信息，请参阅桌面 COSA 数据库设置中的桌面 COSA 专用设置。

下载 COSA/APN 更新电子表格。