Package google.digitalassetlinks.v1

索引

声明

此 API 服务提供“声明”服务，即资产所有者发布资产链接相关信息时使用的工具。使用 API 可以用简单且安全的方式检索语句，而无需直接从来源获取语句。

此 API 返回的所有声明都是代表数字资产（例如网站或 Android 应用）针对其他数字资产做出的声明。每个语句都包含一个源资产、一个目标资产以及一个或多个关系。

这种关系描述了来源资产已声明版权的两项资产之间的关系。例如，特权或权限的委托就属于此类关系。

列表

rpc List(ListRequest) returns (ListResponse)

从给定来源检索与指定目标和语句字符串匹配的所有语句的列表。

该 API 可保证包含安全源资产（例如 HTTPS 网站或 Android 应用）的所有声明都是由这些资产的所有者以安全的方式做出，如 Digital Asset Links 技术设计规范中所述。具体来说，对于不安全网站（即网址以 http:// 而非 https:// 开头），Google 无法做出此保证。

当 API 客户端想要了解两个资源的所有相关方式，或者枚举特定源资源的所有关系时，List 命令最为有用。示例：一项可帮助用户导航到相关项的功能。当某个移动应用在设备上运行时，该功能将使用户可以轻松导航到相应的网站或 Google+ 个人资料。

AndroidAppAsset

描述 Android 应用资源。

字段名称 类型 说明
package_name string Android 应用资源由其 Java 软件包名称自然标识。例如，Google 地图应用使用软件包名称 com.google.android.apps.maps。必填
certificate CertificateInfo

由于不会全局强制实施软件包名称唯一性，因此我们还需要签名证书，该证书与软件包名称相结合，可唯一标识应用。

某些应用的签名密钥会轮替，因此随着时间的推移，它们可能会使用不同的密钥进行签名。我们会将 (package name, cert) 用作唯一 ID，因此系统会将它们视为不同的资源。这通常不会造成任何问题，因为两个版本的应用将做出相同或相似的陈述。不过，在轮替密钥时，对应用做出陈述的其他资源也必须更新。

（请注意，发布和查询语句的语法包含语法糖，可让您轻松指定多个证书已知的应用。）必填

CertificateInfo

描述 X509 证书。

字段名称 类型 说明
sha256_fingerprint string

证书的大写 SHA-265 指纹。从 PEM 证书中可获取该证书，如下所示：

$ keytool -printcert -file $CERTFILE | grep SHA256:
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

也可以改成这样：

$ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
SHA256 Fingerprint=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

在此示例中，此字段的内容将为 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。

如果您无法使用这些工具，则可以将 PEM 证书转换为 DER 格式，计算该字符串的 SHA-256 哈希值，并将结果表示为十六进制字符串（即每个八位字节的大写十六进制表示，以英文冒号分隔）。

素材资源

资产的唯一标识符。

数字资产是一种可识别身份且可寻址的在线实体，通常提供某些服务或内容。例如网站、Android 应用、Twitter 信息流和 Google+ 信息页。

字段名称 类型 说明
联合字段，只有下列其中一项：
web WebAsset 此属性用于指明这是网络资产。
android_app AndroidAppAsset 设置此资源是否为 Android 应用资源。

CheckRequest

用于检查特定资产链接是否存在的消息。

字段名称 类型 说明
source Asset 托管语句列表的来源。这用于将 Check() 调用路由到正确的来源。
relation string

关系的查询字符串。

我们使用 <kind>/<detail> 格式的字符串来识别关系，其中 <kind> 必须是一组预定义的用途类别之一，而 <detail> 是自由格式的小写字母数字字符串，用于描述语句的具体用例。

如需查看受支持关系的最新列表，请参阅我们的 API 文档。

为使查询匹配资产链接，查询和资产链接的关系字符串必须完全匹配。

示例：关系为 delegate_permission/common.handle_all_urls 的查询与关系为 delegate_permission/common.handle_all_urls 的资产链接匹配。
target Asset 语句的目标资产。

CheckResponse

CheckAssetLinks 调用的响应消息。

字段名称 类型 说明
linked bool 如果请求中指定的资产与请求中指定的关系相关联，则设置为 true。必填
max_age Duration 自投放时间起，除非进一步更新，否则响应在多长时间内被视为有效。必填
debug_string string

人类可读的消息，其中包含旨在帮助最终用户理解、重现和调试结果的信息。

该消息将采用英语，我们目前不打算提供任何翻译。

请注意，我们不对此字符串的内容或格式做出任何保证。条款的任何方面都可能会发生更改，恕不另行通知。您不应尝试以程序化方式解析此数据。如果您觉得需要这样做是因为 API 没有以其他方式提供您所需的信息，请首先与我们联系。

ListRequest

用于请求具有指定来源和关系的所有已知语句的消息。

字段名称 类型 说明
source Asset 托管语句列表的来源。这用于将 List() 请求定向到正确的来源。必填
relation string

仅使用与指定关系匹配的关联。

如需了解关系字符串的详细定义，请参阅 Statement 消息。

为了让查询与语句匹配，必须满足以下条件之一：

  • 查询和语句的关系字符串完全匹配，或者
  • 查询的关系字符串为空或缺失。

示例：关系为 delegate_permission/common.handle_all_urls 的查询与关系为 delegate_permission/common.handle_all_urls 的资产链接匹配。

ListResponse

List 调用的响应消息。

字段名称 类型 说明
statements Statement 找到的所有匹配语句的列表。
max_age Duration 自投放时间起，除非进一步更新，否则响应在多长时间内被视为有效。必填
debug_string string

人类可读的消息，其中包含旨在帮助最终用户理解、重现和调试结果的信息。

该消息将采用英语，我们目前不打算提供任何翻译。

请注意，我们不对此字符串的内容或格式做出任何保证。条款的任何方面都可能会发生更改，恕不另行通知。您不应尝试以程序化方式解析此数据。如果您觉得需要这样做是因为 API 没有以其他方式提供您所需的信息，请首先与我们联系。

语句

描述围绕源资产与目标资产之间的关系所做的可靠陈述。

语句始终由源资源发出，要么直接执行，要么委托给存储在其他位置的语句列表。

如需详细了解语句和资源的定义，请参阅我们的 API 文档着陆页。

字段名称 类型 说明
source Asset 每条语句都有一个源资源。必填
relation string

这种关系用于标识对语句的使用方式符合来源资产所有者（即发布该语句的个人或实体）的意图。每个完整的语句都存在某种关系。

我们使用 <kind>/<detail> 格式的字符串来识别关系，其中 <kind> 必须是一组预定义的用途类别之一，而 <detail> 是自由格式的小写字母数字字符串，用于描述语句的具体用例。

如需查看受支持关系的最新列表，请参阅我们的 API 文档。

示例：delegate_permission/common.handle_all_urls（必需）
target Asset 每条语句都有一个目标素材资源。必填

WebAsset

描述网络资产。

字段名称 类型 说明
site string

Web 资产由仅包含 scheme、主机名和端口部分的网址标识。格式为

http[s]://<hostname>[:<port>]

主机名必须是完全限定的：它们必须以一个英文句点 (.) 结尾。

目前仅支持“http”和“https”架构。

端口号以十进制数表示，如果使用标准端口号，则必须省略：80 用于 http，443 用于 https。

我们将此受限网址称为“网站”。共享相同架构、主机名和端口的所有网址都被视为网站的一部分，因此属于该网络资产。

示例：网站为 https://www.google.com 的资源包含以下所有网址：

  • https://www.google.com/
  • https://www.google.com:443/
  • https://www.google.com/foo
  • https://www.google.com/foo?bar
  • https://www.google.com/foo#bar
  • https://user@password:www.google.com/

但不包含以下网址：

  • http://www.google.com/（架构错误）
  • https://google.com/（主机名不匹配）
  • https://www.google.com:444/（端口不匹配）必需