跳到主要内容

2. 请求参数 "authorization_details" (Request Parameter "authorization_details")

请求参数 authorization_details 以 JSON 表示法包含一个对象数组. 每个 JSON 对象包含用于指定某类资源授权需求的数据. 资源类型或访问需求由 type 字段确定, 其定义如下:

type: 授权详情类型的标识符, 表示为字符串. type 字段的值决定包含该字段的对象中允许出现的内容. 在 AS 的上下文中, 该值对于所描述的 API 是唯一的. 此字段为 REQUIRED.

authorization_details 数组 MAY 包含同一类型的多个条目.

图 2 展示了一个类型为 payment_initiation 的 authorization_details, 使用的是上文所示的示例数据:

[
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

图 3 展示了一个组合请求, 该请求同时请求访问账户信息以及发起支付的权限:

[
  {
    "type": "account_information",
    "actions": [
      "list_accounts",
      "read_balances",
      "read_transactions"
    ],
    "locations": [
      "https://example.com/accounts"
    ]
  },
  {
    "type": "payment_initiation",
    "actions": [
      "initiate",
      "status",
      "cancel"
    ],
    "locations": [
      "https://example.com/payments"
    ],
    "instructedAmount": {
      "currency": "EUR",
      "amount": "123.50"
    },
    "creditorName": "Merchant A",
    "creditorAccount": {
      "iban": "DE02100100109307118603"
    },
    "remittanceInformationUnstructured": "Ref Number Merchant"
  }
]

type 字段为 account_information 和 payment_initiation 的 JSON 对象表示不同的 authorization_details, AS 将使用它们来请求同意.

注: AS 随后会将该数据提供给相应的 RS (见第 9 节).

2.1. 授权详情类型 (Authorization Details Types)​

AS 控制对 type 参数值的解释, 以及该 type 参数所允许的对象字段. 但是, type 参数的值通常也会被文档化, 并预期由开发者使用. API 设计者 RECOMMENDED 选择易于复制且不会产生歧义的 type 值. 例如, 某些字形对于同一视觉字符具有多个 Unicode 码点, 开发者可能会输入与 AS 所定义字符不同的字符. 降低潜在混淆的可行方法包括将该值限制为 ASCII [RFC0020] 字符、提供机器可读的数据类型值列表, 或指示开发者直接从文档中复制粘贴.

如果某个应用或 API 预计会跨不同服务器部署, 例如开放标准中的情形, API 设计者 RECOMMENDED 使用其控制下的抗冲突命名空间, 例如由 API 设计者控制的 URI.

以下示例展示了实现如何利用命名空间 https://scheme.example.org/ 来确保 type 值具备抗冲突性:

{
  "type": "https://scheme.example.org/files",
  "locations": [
    "https://example.com/files"
  ],
  "permissions": [
    {
      "path": "/myfiles/A",
      "access": [
        "read"
      ]
    },
    {
      "path": "/myfiles/A/X",
      "access": [
        "read",
        "write"
      ]
    }
  ]
}

2.2. 通用数据字段 (Common Data Fields)​

本规范定义了一组通用数据字段, 设计目标是在不同类型的 API 之间复用. 本规范不要求 API 定义使用这些通用字段, 而是将它们作为可复用的通用组件提供给 API 设计者使用. 所有字段的允许值由受保护的 API 决定, 并由特定的 "type" 值定义.

locations: 字符串数组, 表示资源或 RS 的位置. 这些字符串通常是标识 RS 位置的 URI. 如第 12 节所述, 此字段可允许客户端指定特定 RS.

actions: 字符串数组, 表示要在资源上执行的操作类型.

datatypes: 字符串数组, 表示从资源请求的数据类型.

identifier: 字符串标识符, 指示 API 中可用的特定资源.

privileges: 字符串数组, 表示在资源上请求的特权类型或级别.

当组合使用不同的通用数据字段时, 客户端请求的权限是所有值的笛卡尔积. 该对象表示一个请求: 对象中列出的所有 actions 值可用于对象中列出的所有 locations 值, 并适用于对象中列出的所有 datatypes 值.

在以下示例中, 客户端请求对 customer_information API 中属于客户的联系人和照片同时拥有读取和写入访问权限. 如果该请求获得批准, 客户端会认为它能够使用 API 定义的任意权限组合, 例如读取照片和写入联系人.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read",
      "write"
    ],
    "datatypes": [
      "contacts",
      "photos"
    ]
  }
]

如果客户端希望对其访问权限进行更精细的控制, 可以发送多个对象. 在此示例中, 客户端请求在同一 API 端点中读取联系人并写入照片. 如果该请求获得批准, 客户端将无法写入联系人.

[
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "read"
    ],
    "datatypes": [
      "contacts"
    ]
  },
  {
    "type": "customer_information",
    "locations": [
      "https://example.com/customers"
    ],
    "actions": [
      "write"
    ],
    "datatypes": [
      "photos"
    ]
  }
]

API MAY 定义自己的扩展, 具体取决于相应授权对象的类型. 预计 API 设计者会组合使用本规范定义的通用数据字段以及 API 自身特有的字段.

最后于 更新