You can not select more than 25 topics
Topics must start with a letter or number, can include dashes ('-') and can be up to 35 characters long.
399 lines
18 KiB
399 lines
18 KiB
<html><body>
|
|
<style>
|
|
|
|
body, h1, h2, h3, div, span, p, pre, a {
|
|
margin: 0;
|
|
padding: 0;
|
|
border: 0;
|
|
font-weight: inherit;
|
|
font-style: inherit;
|
|
font-size: 100%;
|
|
font-family: inherit;
|
|
vertical-align: baseline;
|
|
}
|
|
|
|
body {
|
|
font-size: 13px;
|
|
padding: 1em;
|
|
}
|
|
|
|
h1 {
|
|
font-size: 26px;
|
|
margin-bottom: 1em;
|
|
}
|
|
|
|
h2 {
|
|
font-size: 24px;
|
|
margin-bottom: 1em;
|
|
}
|
|
|
|
h3 {
|
|
font-size: 20px;
|
|
margin-bottom: 1em;
|
|
margin-top: 1em;
|
|
}
|
|
|
|
pre, code {
|
|
line-height: 1.5;
|
|
font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
|
|
}
|
|
|
|
pre {
|
|
margin-top: 0.5em;
|
|
}
|
|
|
|
h1, h2, h3, p {
|
|
font-family: Arial, sans serif;
|
|
}
|
|
|
|
h1, h2, h3 {
|
|
border-bottom: solid #CCC 1px;
|
|
}
|
|
|
|
.toc_element {
|
|
margin-top: 0.5em;
|
|
}
|
|
|
|
.firstline {
|
|
margin-left: 2 em;
|
|
}
|
|
|
|
.method {
|
|
margin-top: 1em;
|
|
border: solid 1px #CCC;
|
|
padding: 1em;
|
|
background: #EEE;
|
|
}
|
|
|
|
.details {
|
|
font-weight: bold;
|
|
font-size: 14px;
|
|
}
|
|
|
|
</style>
|
|
|
|
<h1><a href="digitalassetlinks_v1.html">Digital Asset Links API</a> . <a href="digitalassetlinks_v1.statements.html">statements</a></h1>
|
|
<h2>Instance Methods</h2>
|
|
<p class="toc_element">
|
|
<code><a href="#list">list(source_androidApp_packageName=None, relation=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, x__xgafv=None, source_web_site=None)</a></code></p>
|
|
<p class="firstline">Retrieves a list of all statements from a given source that match the</p>
|
|
<h3>Method Details</h3>
|
|
<div class="method">
|
|
<code class="details" id="list">list(source_androidApp_packageName=None, relation=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, x__xgafv=None, source_web_site=None)</code>
|
|
<pre>Retrieves a list of all statements from a given source that match the
|
|
specified target and statement string.
|
|
|
|
The API guarantees that all statements with secure source assets, such as
|
|
HTTPS websites or Android apps, have been made in a secure way by the owner
|
|
of those assets, as described in the [Digital Asset Links technical design
|
|
specification](https://github.com/google/digitalassetlinks/blob/master/well-known/details.md).
|
|
Specifically, you should consider that for insecure websites (that is,
|
|
where the URL starts with `http://` instead of `https://`), this guarantee
|
|
cannot be made.
|
|
|
|
The `List` command is most useful in cases where the API client wants to
|
|
know all the ways in which two assets are related, or enumerate all the
|
|
relationships from a particular source asset. Example: a feature that
|
|
helps users navigate to related items. When a mobile app is running on a
|
|
device, the feature would make it easy to navigate to the corresponding web
|
|
site or Google+ profile.
|
|
|
|
Args:
|
|
source_androidApp_packageName: string, Android App assets are naturally identified by their Java package name.
|
|
For example, the Google Maps app uses the package name
|
|
`com.google.android.apps.maps`.
|
|
REQUIRED
|
|
relation: string, Use only associations that match the specified relation.
|
|
|
|
See the [`Statement`](#Statement) message for a detailed definition of
|
|
relation strings.
|
|
|
|
For a query to match a statement, one of the following must be true:
|
|
|
|
* both the query's and the statement's relation strings match exactly,
|
|
or
|
|
* the query's relation string is empty or missing.
|
|
|
|
Example: A query with relation `delegate_permission/common.handle_all_urls`
|
|
matches an asset link with relation
|
|
`delegate_permission/common.handle_all_urls`.
|
|
source_androidApp_certificate_sha256Fingerprint: string, The uppercase SHA-265 fingerprint of the certificate. From the PEM
|
|
certificate, it can be acquired like this:
|
|
|
|
$ 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
|
|
|
|
or like this:
|
|
|
|
$ 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
|
|
|
|
In this example, the contents of this field would be `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`.
|
|
|
|
If these tools are not available to you, you can convert the PEM
|
|
certificate into the DER format, compute the SHA-256 hash of that string
|
|
and represent the result as a hexstring (that is, uppercase hexadecimal
|
|
representations of each octet, separated by colons).
|
|
x__xgafv: string, V1 error format.
|
|
Allowed values
|
|
1 - v1 error format
|
|
2 - v2 error format
|
|
source_web_site: string, Web assets are identified by a URL that contains only the scheme, hostname
|
|
and port parts. The format is
|
|
|
|
http[s]://<hostname>[:<port>]
|
|
|
|
Hostnames must be fully qualified: they must end in a single period
|
|
("`.`").
|
|
|
|
Only the schemes "http" and "https" are currently allowed.
|
|
|
|
Port numbers are given as a decimal number, and they must be omitted if the
|
|
standard port numbers are used: 80 for http and 443 for https.
|
|
|
|
We call this limited URL the "site". All URLs that share the same scheme,
|
|
hostname and port are considered to be a part of the site and thus belong
|
|
to the web asset.
|
|
|
|
Example: the asset with the site `https://www.google.com` contains all
|
|
these URLs:
|
|
|
|
* `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/`
|
|
|
|
But it does not contain these URLs:
|
|
|
|
* `http://www.google.com/` (wrong scheme)
|
|
* `https://google.com/` (hostname does not match)
|
|
* `https://www.google.com:444/` (port does not match)
|
|
REQUIRED
|
|
|
|
Returns:
|
|
An object of the form:
|
|
|
|
{ # Response message for the List call.
|
|
"errorCode": [ # Error codes that describe the result of the List operation.
|
|
"A String",
|
|
],
|
|
"statements": [ # A list of all the matching statements that have been found.
|
|
{ # Describes a reliable statement that has been made about the relationship
|
|
# between a source asset and a target asset.
|
|
#
|
|
# Statements are always made by the source asset, either directly or by
|
|
# delegating to a statement list that is stored elsewhere.
|
|
#
|
|
# For more detailed definitions of statements and assets, please refer
|
|
# to our [API documentation landing
|
|
# page](/digital-asset-links/v1/getting-started).
|
|
"source": { # Uniquely identifies an asset. # Every statement has a source asset.
|
|
# REQUIRED
|
|
#
|
|
# A digital asset is an identifiable and addressable online entity that
|
|
# typically provides some service or content. Examples of assets are websites,
|
|
# Android apps, Twitter feeds, and Plus Pages.
|
|
"web": { # Describes a web asset. # Set if this is a web asset.
|
|
"site": "A String", # Web assets are identified by a URL that contains only the scheme, hostname
|
|
# and port parts. The format is
|
|
#
|
|
# http[s]://<hostname>[:<port>]
|
|
#
|
|
# Hostnames must be fully qualified: they must end in a single period
|
|
# ("`.`").
|
|
#
|
|
# Only the schemes "http" and "https" are currently allowed.
|
|
#
|
|
# Port numbers are given as a decimal number, and they must be omitted if the
|
|
# standard port numbers are used: 80 for http and 443 for https.
|
|
#
|
|
# We call this limited URL the "site". All URLs that share the same scheme,
|
|
# hostname and port are considered to be a part of the site and thus belong
|
|
# to the web asset.
|
|
#
|
|
# Example: the asset with the site `https://www.google.com` contains all
|
|
# these URLs:
|
|
#
|
|
# * `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/`
|
|
#
|
|
# But it does not contain these URLs:
|
|
#
|
|
# * `http://www.google.com/` (wrong scheme)
|
|
# * `https://google.com/` (hostname does not match)
|
|
# * `https://www.google.com:444/` (port does not match)
|
|
# REQUIRED
|
|
},
|
|
"androidApp": { # Describes an android app asset. # Set if this is an Android App asset.
|
|
"packageName": "A String", # Android App assets are naturally identified by their Java package name.
|
|
# For example, the Google Maps app uses the package name
|
|
# `com.google.android.apps.maps`.
|
|
# REQUIRED
|
|
"certificate": { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
|
|
# require a signing certificate, which in combination with the package name
|
|
# uniquely identifies an app.
|
|
#
|
|
# Some apps' signing keys are rotated, so they may be signed by different
|
|
# keys over time. We treat these as distinct assets, since we use (package
|
|
# name, cert) as the unique ID. This should not normally pose any problems
|
|
# as both versions of the app will make the same or similar statements.
|
|
# Other assets making statements about the app will have to be updated when a
|
|
# key is rotated, however.
|
|
#
|
|
# (Note that the syntaxes for publishing and querying for statements contain
|
|
# syntactic sugar to easily let you specify apps that are known by multiple
|
|
# certificates.)
|
|
# REQUIRED
|
|
"sha256Fingerprint": "A String", # The uppercase SHA-265 fingerprint of the certificate. From the PEM
|
|
# certificate, it can be acquired like this:
|
|
#
|
|
# $ 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
|
|
#
|
|
# or like this:
|
|
#
|
|
# $ 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
|
|
#
|
|
# In this example, the contents of this field would be `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`.
|
|
#
|
|
# If these tools are not available to you, you can convert the PEM
|
|
# certificate into the DER format, compute the SHA-256 hash of that string
|
|
# and represent the result as a hexstring (that is, uppercase hexadecimal
|
|
# representations of each octet, separated by colons).
|
|
},
|
|
},
|
|
},
|
|
"relation": "A String", # The relation identifies the use of the statement as intended by the source
|
|
# asset's owner (that is, the person or entity who issued the statement).
|
|
# Every complete statement has a relation.
|
|
#
|
|
# We identify relations with strings of the format `<kind>/<detail>`, where
|
|
# `<kind>` must be one of a set of pre-defined purpose categories, and
|
|
# `<detail>` is a free-form lowercase alphanumeric string that describes the
|
|
# specific use case of the statement.
|
|
#
|
|
# Refer to [our API documentation](/digital-asset-links/v1/relation-strings)
|
|
# for the current list of supported relations.
|
|
#
|
|
# Example: `delegate_permission/common.handle_all_urls`
|
|
# REQUIRED
|
|
"target": { # Uniquely identifies an asset. # Every statement has a target asset.
|
|
# REQUIRED
|
|
#
|
|
# A digital asset is an identifiable and addressable online entity that
|
|
# typically provides some service or content. Examples of assets are websites,
|
|
# Android apps, Twitter feeds, and Plus Pages.
|
|
"web": { # Describes a web asset. # Set if this is a web asset.
|
|
"site": "A String", # Web assets are identified by a URL that contains only the scheme, hostname
|
|
# and port parts. The format is
|
|
#
|
|
# http[s]://<hostname>[:<port>]
|
|
#
|
|
# Hostnames must be fully qualified: they must end in a single period
|
|
# ("`.`").
|
|
#
|
|
# Only the schemes "http" and "https" are currently allowed.
|
|
#
|
|
# Port numbers are given as a decimal number, and they must be omitted if the
|
|
# standard port numbers are used: 80 for http and 443 for https.
|
|
#
|
|
# We call this limited URL the "site". All URLs that share the same scheme,
|
|
# hostname and port are considered to be a part of the site and thus belong
|
|
# to the web asset.
|
|
#
|
|
# Example: the asset with the site `https://www.google.com` contains all
|
|
# these URLs:
|
|
#
|
|
# * `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/`
|
|
#
|
|
# But it does not contain these URLs:
|
|
#
|
|
# * `http://www.google.com/` (wrong scheme)
|
|
# * `https://google.com/` (hostname does not match)
|
|
# * `https://www.google.com:444/` (port does not match)
|
|
# REQUIRED
|
|
},
|
|
"androidApp": { # Describes an android app asset. # Set if this is an Android App asset.
|
|
"packageName": "A String", # Android App assets are naturally identified by their Java package name.
|
|
# For example, the Google Maps app uses the package name
|
|
# `com.google.android.apps.maps`.
|
|
# REQUIRED
|
|
"certificate": { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
|
|
# require a signing certificate, which in combination with the package name
|
|
# uniquely identifies an app.
|
|
#
|
|
# Some apps' signing keys are rotated, so they may be signed by different
|
|
# keys over time. We treat these as distinct assets, since we use (package
|
|
# name, cert) as the unique ID. This should not normally pose any problems
|
|
# as both versions of the app will make the same or similar statements.
|
|
# Other assets making statements about the app will have to be updated when a
|
|
# key is rotated, however.
|
|
#
|
|
# (Note that the syntaxes for publishing and querying for statements contain
|
|
# syntactic sugar to easily let you specify apps that are known by multiple
|
|
# certificates.)
|
|
# REQUIRED
|
|
"sha256Fingerprint": "A String", # The uppercase SHA-265 fingerprint of the certificate. From the PEM
|
|
# certificate, it can be acquired like this:
|
|
#
|
|
# $ 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
|
|
#
|
|
# or like this:
|
|
#
|
|
# $ 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
|
|
#
|
|
# In this example, the contents of this field would be `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`.
|
|
#
|
|
# If these tools are not available to you, you can convert the PEM
|
|
# certificate into the DER format, compute the SHA-256 hash of that string
|
|
# and represent the result as a hexstring (that is, uppercase hexadecimal
|
|
# representations of each octet, separated by colons).
|
|
},
|
|
},
|
|
},
|
|
},
|
|
],
|
|
"maxAge": "A String", # From serving time, how much longer the response should be considered valid
|
|
# barring further updates.
|
|
# REQUIRED
|
|
"debugString": "A String", # Human-readable message containing information intended to help end users
|
|
# understand, reproduce and debug the result.
|
|
#
|
|
#
|
|
# The message will be in English and we are currently not planning to offer
|
|
# any translations.
|
|
#
|
|
# Please note that no guarantees are made about the contents or format of
|
|
# this string. Any aspect of it may be subject to change without notice.
|
|
# You should not attempt to programmatically parse this data. For
|
|
# programmatic access, use the error_code field below.
|
|
}</pre>
|
|
</div>
|
|
|
|
</body></html> |