Skip to main content

2. 请求参数 "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"
  }
]

具有account_information和payment_initiation类型字段的JSON对象表示AS用于请求同意的不同授权详情。

注意: AS将随后使该数据对相应的RS可用(参见第9节)。

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

AS控制type参数值的解释以及type参数允许的对象字段。但是,type参数的值通常也被记录并旨在供开发人员使用。建议(RECOMMENDED)API设计者选择易于无歧义复制的类型值。例如,某些字形对于相同的视觉字符具有多个Unicode代码点,开发人员可能会键入与AS定义的不同字符。减少潜在混淆的可能方法是将值限制为ASCII[RFC0020]字符、提供数据类型值的机器可读列表,或指示开发人员直接从文档中复制和粘贴。

如果应用程序或API预期将部署在不同的服务器上,例如在开放标准的情况下,建议(RECOMMENDED)API设计者使用其控制下的抗冲突命名空间,例如API设计者控制的URI。

以下示例显示了实现如何利用命名空间https://scheme.example.org/来确保抗冲突的类型值:

{
  "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。此字段可以允许客户端指定特定的RS,如第12节所述。

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本身的字段的组合。

Last updated on