保存地址，按需使用。

如何开始

订阅 DEV 计划，用 Microsoft 账户登录门户并关联购买，然后申请准备。确认组织、合同、Vault、应用权限与保留期限，批准并激活后用虚拟数据测试。购买不会自动创建环境或赋予数据权限。生产使用条件另行确认。

连接前的准备

与 OneNym 确认购买合同、使用组织、Vault 租户、商家和配送应用 ID、用途、允许字段及保留期限。获取 API HTTPS origin、API application ID 和 directory tenant ID。网站和购买门户不是 API 地址。购买后仍需配置与批准。

使用 Microsoft Entra 应用 Bearer token。Azure 可用 Managed Identity，证书方式以私钥认证应用并获取令牌，并非通信层 mTLS。当前 Vault 信任一个 Entra 目录，不会自动支持其他组织。凭据只放在后端。

ONENYM_API_URL=<API HTTPS origin>
ONENYM_API_APPLICATION_ID=<API application ID>
directory tenant ID / merchant client ID / carrier client ID

Authorization: Bearer <application-access-token>

运行本地集成示例

向 OneNym 获取 SDK 源码和示例包，解压到新文件夹。需要 .NET 10 SDK、PowerShell 7 及 NuGet 网络访问。下列命令无需 Azure 账户即可用虚拟数据验证 18 个操作。本地认证、SQLite 和密钥仅用于演示，不可用于绕过服务认证或合同。使用附带的 SDK 源码，不以公开 NuGet 发布为前提。

dotnet --version
pwsh --version
pwsh -NoProfile -File ./samples/OneNym.Vault.Pilot/run-local.ps1

RESULT passed=True; steps=18; elapsedMs=…; cleanup=True
PASS isolated customer quickstart

从订单到配送

1. 01 / REGISTER

   通过已认证的 API 注册地址。Vault 加密保存并返回难以预测的代理 ID。还需设计输入与接入路径，避免在服务器或日志中保留副本。

2. 02 / REFERENCE

   订单数据库保存订单号和代理 ID。ID 既不是地址，也不是查询权限。接入不会自动删除已有副本，仍需迁移和清理。

3. 03 / AUTHORIZE

   将订单、代理 ID、接收应用、字段与到期时间绑定，并签发有次数限制的令牌。持有令牌本身并不足以访问。

4. 04 / RETRIEVE

   认证应用并检查组织、订单、用途、字段、到期时间、次数与合同状态。允许字段以明文返回，接收方也需管理存储和日志。

POST /v1/addresses
  → proxyId: nym_…

PUT /v1/shipping-orders
  proxyId + orderReference + recipientClientId + fields + expiresAt
  → orderId + version

POST /v1/shipping-orders/{orderId}/grants
  orderVersion + expiresAt + maxUses
  → token: nrt_…

POST /v1/retrieval-grants/redeem
  Authorization: Bearer <application-access-token>
  X-OneNym-Retrieval-Token: <retrieval-token>
  orderId + orderReference + purpose + fields
  → permitted fields

这些示例用于说明设计。字段名及值仅供演示，并非可执行的 API 参考。

实现会在内存中解密整个地址记录，再仅返回允许的字段，并非逐字段加密。接收方须管理取得的明文，客户也须管理注册前系统中的日志与存储。

API 与 SDK 操作

每项操作均需应用 Bearer token 和相应权限。配送获取还需 X-OneNym-Retrieval-Token。使用 UTF-8 JSON，目的为 shipping。GET、撤销和 DELETE 不带正文。示例假设 merchant 和 carrier 已认证、persistedKey 已在注册前保存、orderReference 不含个人信息。可运行的程序请使用示例包。

using OneNym.Vault.Client;

var fields = new[] { "recipientName", "postalCode", "addressLine1" };
var registration = await merchant.RegisterAsync(new CreateAddress {
    Address = new AddressData {
        RecipientName = "Demo Recipient", PostalCode = "000-0000",
        CountryCode = "JP", AddressLine1 = "Dummy address",
        Locality = "Demo city"
    },
    RetainUntil = DateTimeOffset.UtcNow.AddDays(1)
}, persistedKey);

var order = await merchant.BindAsync(new BindOrder(
    orderReference, registration.ProxyId, carrierClientId, fields,
    DateTimeOffset.UtcNow.AddHours(1)));
var grant = await merchant.IssueAsync(
    order.OrderId, order.Version, DateTimeOffset.UtcNow.AddMinutes(5));
var address = await carrier.RedeemAsync(
    order.OrderId, orderReference, grant.Token, fields);

字段、到期与使用次数

支持下列七个地址字段。countryCode 为两个大写字母；JSON 正文上限为 16,384 字节。初始最长保留期限为 30 天，以部署配置为准。配送令牌不得晚于地址或订单到期，且签发后最长 15 分钟。API maxUses 为 1–5，标准 SDK 为一次。按 UTC 秒计算，到期时刻即拒绝访问。不验证地址实际存在或可配送性。

recipientName   1–200
postalCode      1–32
countryCode     [A-Z]{2}
addressLine1    1–300
addressLine2    null / 0–300
locality        1–100
region          null / 0–100

地址更正、订单与撤销

更正时注册新地址，而非原地修改。查询当前绑定，将其 Version 作为 expectedVersion 更改订单，再签发新版本令牌。订单版本变化会阻止所有旧版本令牌。同版本追加签发不会撤销现有令牌。删除旧地址前检查其他订单及保留要求。已取得的明文无法收回。

var current = await merchant.InspectOrderAsync(orderReference);
var changed = await merchant.BindAsync(new BindOrder(
    orderReference, newRegistration.ProxyId, carrierClientId, fields,
    newOrderExpiry, ExpectedVersion: current.Version));
var newGrant = await merchant.IssueAsync(
    changed.OrderId, changed.Version, newGrantExpiry);

// BindOrder = complete desired binding, not a partial patch.
// Keep unknown prior outcomes for reconciliation; never blindly retry.

错误与未知结果

SDK 不自动重试。超时、取消或 503 可能发生在保存或令牌消耗之后。不能把失败响应当作未执行，应按操作核对结果。

400 / 413 / 415

检查输入、JSON 重复或未知字段、类型及期限。400 表示输入无效，413 为正文超限，415 为不支持的格式。不要悄悄改值重发。

401 / 403 / 404

检查身份、audience、应用权限、字段、用途及合同。404 也会隐藏其他所有者的数据或已撤销、删除的资源，不能用来证明存在或不存在。

409

检查到期、次数、订单版本和幂等键冲突。重新查询绑定并处理并发修改。不要自动换键或签发新令牌。

429 / Retry-After

已达到配置的限制。遵循 Retry-After、限制并发并判断能否重试。这不保证排队时长或处理容量。

SDK / 503

SDK 408/timeout_outcome_unknown、0/transport_unavailable、502/invalid_response、取消及 API 503 可能留下未知结果。注册只能用相同的已保存键、原始正文和到期时间恢复。注册凭据最长保留 24 小时或至地址保留期结束，以较早者为准。查询订单 binding。已签发的原始令牌无法再次读取；先核对配送处理再决定重发或撤销。

联系支持时提供 HTTP 状态、时间及可用的 trace ID。不要发送地址正文、Bearer、证书私钥或配送令牌。

已实现和验证的范围

已实现注册、限定字段获取、带版本的订单变更、配送令牌签发与次数限制、撤销、删除和到期清理。通过 SDK、隔离 SQL 及真实 Azure MI、Key Vault、Azure SQL 和历史存储验证正常流程、拒绝访问、并发及故障恢复。其他组织实际购买和同意、Microsoft 实际暂停与恢复通知仍待验收。这不构成生产 SLA 或所有配置的容量保证。

FAQ

相关技术设计