语句列表语法

声明列表是位于熟知位置的 JSON 编码文件或代码段。

声明列表的位置

如需了解此列表应存储在何处，请参阅创建语句列表。

语法

声明列表或代码段包含一个 JSON 数组，其中包含一个或多个网站或应用声明（以 JSON 对象的形式表示）。这些语句可以按任意顺序排列。一般语法如下：

[
  {
    "relation": ["relation_string"],
    "target": {target_object}
  } , ...
]

relation

一个包含一个或多个字符串的数组，用于描述声明的且与目标相关的一个或多个关系。请参阅已定义的关系字符串列表。示例： delegate_permission/common.handle_all_urls

目标

相应声明所适用的目标资产。可用的目标类型：

• 网站目标

  "target": {
    "namespace": "web",
    "site": "site_root_url"
  }

  命名空间

  对于网站必须为 web。

  网站

  声明所针对的网站的 URI，格式为 http[s]://<hostname>[:<port>]，其中 <hostname> 是完全限定的，在为 HTTP 使用端口 80 或为 HTTPS 使用端口 443 时必须省略 <port>。网站目标只能是根网域；您不能将其限制为仅与特定子目录相关联；此根网域下的所有目录都将匹配。子网域不应被视为匹配，也就是说，如果声明文件托管在 www.example.com 上，则 www.puppies.example.com 不应被视为匹配。如需了解网站目标匹配方面的规则和示例，请参阅目标文档。示例： http://www.example.com

• Android 应用目标平台

  "target": {
    "namespace": "android_app",
    "package_name": "fully_qualified_package_name",
    "sha256_cert_fingerprints": ["cert_fingerprint"]
  }

  命名空间

  对于 Android 应用，必须为 android_app。

  package_name

  相应语句所适用的应用的完全限定软件包名称。示例： com.google.android.apps.maps

  sha256_cert_fingerprints

  相应应用的证书的大写 SHA265 指纹。您可以使用 openssl 或 Java keytool 计算此值，如下所示：

  • openssl x509 -in $CERTFILE -noout -fingerprint -sha256
  • keytool -printcert -file $CERTFILE | grep SHA256

  示例： ["14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5"]。

  如果您的应用使用的是 Play 应用签名，则通过在本地运行 keytool 或 openssl 生成的证书指纹通常与用户设备上的证书指纹不匹配。您可以在 Play 管理中心开发者账号的 Release > Setup > App Integrity 下验证您是否为应用使用了 Play 应用签名；如果使用了，您还会在同一页面上找到正确的 Digital Asset Links JSON 代码段。

relation_extensions（可选）

您可以向声明添加可选的 relation_extensions 字段，以提供有关您要授予的权限和关联的更多信息。此字段应是一个对象，其中每个键都是一个关系字符串，而值是一个包含相应关系扩展的对象。请求这些声明的客户端需要更新，以遵循这些字段。

例如，delegate_permission/common.handle_all_urls 关系的 relation_extensions 可能如下所示：

  {
    "relation": ["delegate_permission/common.handle_all_urls"],
    "target": {
      "namespace": "android_app",
      "package_name": "com.example.app",
      "sha256_cert_fingerprints": ["..."]
    },
    "relation_extensions": {
      "delegate_permission/common.handle_all_urls": {...}
    }
  }
  

当请求中设置了 return_relation_extensions=true 参数时，DAL API 支持在 API 调用中返回 relation_extensions。

声明列表示例

以下是一个包含网站和应用相关声明的网站声明列表示例：http://example.digitalassetlinks.org/.well-known/assetlinks.json

扩容到数十条或更多条声明

在某些情况下，正文可能需要针对不同的目标做出许多不同的陈述，或者可能需要由不同的正文针对同一组目标做出陈述。例如，一个网站可能在许多不同的国家/地区顶级网域中提供，并且所有这些网域都可能希望声明同一移动应用。

对于这些情况，include 语句可能会有所帮助。 借助此机制，您可以设置从许多不同正文到某个中心位置的指针，该中心位置定义了所有正文的语句。

例如，您可能决定将中央位置设为 `https://example.com/includedstatements.json`。此文件可以配置为包含与上述示例中相同的内容。

如需设置从网站到包含文件的指针，请将 `https://example.com/.well-known/assetlinks.json` 更改为：

[{
  "include": "https://example.com/includedstatements.json"
}]

如需设置从 Android 应用到包含文件的指针，请将 `res/values/strings.xml` 更改为：

<resources>
  ...
  <string name="asset_statements">
    [{
      \"include\": \"https://example.com/includedstatements.json\"
    }]
  </string>
</resources>

更多信息

如需详细了解声明列表格式和底层概念，请参阅我们的规范文档。