Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / 4ed7d3f9b61ac35e08a22b4995076a95451cf7c8 / . / docs / dyn / digitalassetlinks_v1.statements.html
blob: 7517f915748cc7e2b353836b4c1f888572e00c90 [file] [log] [blame]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]1<html><body>
2<style>
3
4body, h1, h2, h3, div, span, p, pre, a {
5 margin: 0;
6 padding: 0;
7 border: 0;
8 font-weight: inherit;
9 font-style: inherit;
10 font-size: 100%;
11 font-family: inherit;
12 vertical-align: baseline;
13}
14
15body {
16 font-size: 13px;
17 padding: 1em;
18}
19
20h1 {
21 font-size: 26px;
22 margin-bottom: 1em;
23}
24
25h2 {
26 font-size: 24px;
27 margin-bottom: 1em;
28}
29
30h3 {
31 font-size: 20px;
32 margin-bottom: 1em;
33 margin-top: 1em;
34}
35
36pre, code {
37 line-height: 1.5;
38 font-family: Monaco, 'DejaVu Sans Mono', 'Bitstream Vera Sans Mono', 'Lucida Console', monospace;
39}
40
41pre {
42 margin-top: 0.5em;
43}
44
45h1, h2, h3, p {
46 font-family: Arial, sans serif;
47}
48
49h1, h2, h3 {
50 border-bottom: solid #CCC 1px;
51}
52
53.toc_element {
54 margin-top: 0.5em;
55}
56
57.firstline {
58 margin-left: 2 em;
59}
60
61.method {
62 margin-top: 1em;
63 border: solid 1px #CCC;
64 padding: 1em;
65 background: #EEE;
66}
67
68.details {
69 font-weight: bold;
70 font-size: 14px;
71}
72
73</style>
74
75<h1><a href="digitalassetlinks_v1.html">Digital Asset Links API</a> . <a href="digitalassetlinks_v1.statements.html">statements</a></h1>
76<h2>Instance Methods</h2>
77<p class="toc_element">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]78 <code><a href="#list">list(source_web_site=None, source_androidApp_packageName=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, relation=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]79<p class="firstline">Retrieves a list of all statements from a given source that match the</p>
80<h3>Method Details</h3>
81<div class="method">
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]82 <code class="details" id="list">list(source_web_site=None, source_androidApp_packageName=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, relation=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]83 <pre>Retrieves a list of all statements from a given source that match the
84specified target and statement string.
85
86The API guarantees that all statements with secure source assets, such as
87HTTPS websites or Android apps, have been made in a secure way by the owner
88of those assets, as described in the [Digital Asset Links technical design
89specification](https://github.com/google/digitalassetlinks/blob/master/well-known/details.md).
90Specifically, you should consider that for insecure websites (that is,
91where the URL starts with `http://` instead of `https://`), this guarantee
92cannot be made.
93
94The `List` command is most useful in cases where the API client wants to
95know all the ways in which two assets are related, or enumerate all the
96relationships from a particular source asset. Example: a feature that
97helps users navigate to related items. When a mobile app is running on a
98device, the feature would make it easy to navigate to the corresponding web
99site or Google+ profile.
100
101Args:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]102 source_web_site: string, Web assets are identified by a URL that contains only the scheme, hostname
103and port parts. The format is
104
105 http[s]://&lt;hostname&gt;[:&lt;port&gt;]
106
107Hostnames must be fully qualified: they must end in a single period
108(&quot;`.`&quot;).
109
110Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
111
112Port numbers are given as a decimal number, and they must be omitted if the
113standard port numbers are used: 80 for http and 443 for https.
114
115We call this limited URL the &quot;site&quot;. All URLs that share the same scheme,
116hostname and port are considered to be a part of the site and thus belong
117to the web asset.
118
119Example: the asset with the site `https://www.google.com` contains all
120these URLs:
121
122 * `https://www.google.com/`
123 * `https://www.google.com:443/`
124 * `https://www.google.com/foo`
125 * `https://www.google.com/foo?bar`
126 * `https://www.google.com/foo#bar`
127 * `https://user@password:www.google.com/`
128
129But it does not contain these URLs:
130
131 * `http://www.google.com/` (wrong scheme)
132 * `https://google.com/` (hostname does not match)
133 * `https://www.google.com:444/` (port does not match)
134REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]135 source_androidApp_packageName: string, Android App assets are naturally identified by their Java package name.
136For example, the Google Maps app uses the package name
137`com.google.android.apps.maps`.
138REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]139 source_androidApp_certificate_sha256Fingerprint: string, The uppercase SHA-265 fingerprint of the certificate. From the PEM
140 certificate, it can be acquired like this:
141
142 $ keytool -printcert -file $CERTFILE | grep SHA256:
143 SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
144 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
145
146or like this:
147
148 $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
149 SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
150 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
151
152In this example, the contents of this field would be `14:6D:E9:83:C5:73:
15306:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
15444:E5`.
155
156If these tools are not available to you, you can convert the PEM
157certificate into the DER format, compute the SHA-256 hash of that string
158and represent the result as a hexstring (that is, uppercase hexadecimal
159representations of each octet, separated by colons).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]160 relation: string, Use only associations that match the specified relation.
161
162See the [`Statement`](#Statement) message for a detailed definition of
163relation strings.
164
165For a query to match a statement, one of the following must be true:
166
167* both the query&#x27;s and the statement&#x27;s relation strings match exactly,
168 or
169* the query&#x27;s relation string is empty or missing.
170
171Example: A query with relation `delegate_permission/common.handle_all_urls`
172matches an asset link with relation
173`delegate_permission/common.handle_all_urls`.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]174 x__xgafv: string, V1 error format.
175 Allowed values
176 1 - v1 error format
177 2 - v2 error format
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]178
179Returns:
180 An object of the form:
181
182 { # Response message for the List call.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]183 &quot;errorCode&quot;: [ # Error codes that describe the result of the List operation.
184 &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]185 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]186 &quot;statements&quot;: [ # A list of all the matching statements that have been found.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]187 { # Describes a reliable statement that has been made about the relationship
188 # between a source asset and a target asset.
189 #
190 # Statements are always made by the source asset, either directly or by
191 # delegating to a statement list that is stored elsewhere.
192 #
193 # For more detailed definitions of statements and assets, please refer
194 # to our [API documentation landing
195 # page](/digital-asset-links/v1/getting-started).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]196 &quot;target&quot;: { # Uniquely identifies an asset. # Every statement has a target asset.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]197 # REQUIRED
198 #
199 # A digital asset is an identifiable and addressable online entity that
200 # typically provides some service or content. Examples of assets are websites,
201 # Android apps, Twitter feeds, and Plus Pages.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]202 &quot;web&quot;: { # Describes a web asset. # Set if this is a web asset.
203 &quot;site&quot;: &quot;A String&quot;, # Web assets are identified by a URL that contains only the scheme, hostname
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]204 # and port parts. The format is
205 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]206 # http[s]://&lt;hostname&gt;[:&lt;port&gt;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]207 #
208 # Hostnames must be fully qualified: they must end in a single period
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]209 # (&quot;`.`&quot;).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]210 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]211 # Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]212 #
213 # Port numbers are given as a decimal number, and they must be omitted if the
214 # standard port numbers are used: 80 for http and 443 for https.
215 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]216 # We call this limited URL the &quot;site&quot;. All URLs that share the same scheme,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]217 # hostname and port are considered to be a part of the site and thus belong
218 # to the web asset.
219 #
220 # Example: the asset with the site `https://www.google.com` contains all
221 # these URLs:
222 #
223 # * `https://www.google.com/`
224 # * `https://www.google.com:443/`
225 # * `https://www.google.com/foo`
226 # * `https://www.google.com/foo?bar`
227 # * `https://www.google.com/foo#bar`
228 # * `https://user@password:www.google.com/`
229 #
230 # But it does not contain these URLs:
231 #
232 # * `http://www.google.com/` (wrong scheme)
233 # * `https://google.com/` (hostname does not match)
234 # * `https://www.google.com:444/` (port does not match)
235 # REQUIRED
236 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]237 &quot;androidApp&quot;: { # Describes an android app asset. # Set if this is an Android App asset.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame^]238 &quot;packageName&quot;: &quot;A String&quot;, # Android App assets are naturally identified by their Java package name.
239 # For example, the Google Maps app uses the package name
240 # `com.google.android.apps.maps`.
241 # REQUIRED
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]242 &quot;certificate&quot;: { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]243 # require a signing certificate, which in combination with the package name
244 # uniquely identifies an app.
245 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]246 # Some apps&#x27; signing keys are rotated, so they may be signed by different
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]247 # keys over time. We treat these as distinct assets, since we use (package
248 # name, cert) as the unique ID. This should not normally pose any problems
249 # as both versions of the app will make the same or similar statements.
250 # Other assets making statements about the app will have to be updated when a
251 # key is rotated, however.
252 #
253 # (Note that the syntaxes for publishing and querying for statements contain
254 # syntactic sugar to easily let you specify apps that are known by multiple
255 # certificates.)
256 # REQUIRED
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]257 &quot;sha256Fingerprint&quot;: &quot;A String&quot;, # The uppercase SHA-265 fingerprint of the certificate. From the PEM
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]258 # certificate, it can be acquired like this:
259 #
260 # $ keytool -printcert -file $CERTFILE | grep SHA256:
261 # SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
262 # 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
263 #
264 # or like this:
265 #
266 # $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
267 # SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
268 # 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
269 #
270 # In this example, the contents of this field would be `14:6D:E9:83:C5:73:
271 # 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
272 # 44:E5`.
273 #
274 # If these tools are not available to you, you can convert the PEM
275 # certificate into the DER format, compute the SHA-256 hash of that string
276 # and represent the result as a hexstring (that is, uppercase hexadecimal
277 # representations of each octet, separated by colons).
278 },
279 },
280 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]281 &quot;source&quot;: { # Uniquely identifies an asset. # Every statement has a source asset.
282 # REQUIRED
283 #
284 # A digital asset is an identifiable and addressable online entity that
285 # typically provides some service or content. Examples of assets are websites,
286 # Android apps, Twitter feeds, and Plus Pages.
287 &quot;web&quot;: { # Describes a web asset. # Set if this is a web asset.
288 &quot;site&quot;: &quot;A String&quot;, # Web assets are identified by a URL that contains only the scheme, hostname
289 # and port parts. The format is
290 #
291 # http[s]://&lt;hostname&gt;[:&lt;port&gt;]
292 #
293 # Hostnames must be fully qualified: they must end in a single period
294 # (&quot;`.`&quot;).
295 #
296 # Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
297 #
298 # Port numbers are given as a decimal number, and they must be omitted if the
299 # standard port numbers are used: 80 for http and 443 for https.
300 #
301 # We call this limited URL the &quot;site&quot;. All URLs that share the same scheme,
302 # hostname and port are considered to be a part of the site and thus belong
303 # to the web asset.
304 #
305 # Example: the asset with the site `https://www.google.com` contains all
306 # these URLs:
307 #
308 # * `https://www.google.com/`
309 # * `https://www.google.com:443/`
310 # * `https://www.google.com/foo`
311 # * `https://www.google.com/foo?bar`
312 # * `https://www.google.com/foo#bar`
313 # * `https://user@password:www.google.com/`
314 #
315 # But it does not contain these URLs:
316 #
317 # * `http://www.google.com/` (wrong scheme)
318 # * `https://google.com/` (hostname does not match)
319 # * `https://www.google.com:444/` (port does not match)
320 # REQUIRED
321 },
322 &quot;androidApp&quot;: { # Describes an android app asset. # Set if this is an Android App asset.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame^]323 &quot;packageName&quot;: &quot;A String&quot;, # Android App assets are naturally identified by their Java package name.
324 # For example, the Google Maps app uses the package name
325 # `com.google.android.apps.maps`.
326 # REQUIRED
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]327 &quot;certificate&quot;: { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
328 # require a signing certificate, which in combination with the package name
329 # uniquely identifies an app.
330 #
331 # Some apps&#x27; signing keys are rotated, so they may be signed by different
332 # keys over time. We treat these as distinct assets, since we use (package
333 # name, cert) as the unique ID. This should not normally pose any problems
334 # as both versions of the app will make the same or similar statements.
335 # Other assets making statements about the app will have to be updated when a
336 # key is rotated, however.
337 #
338 # (Note that the syntaxes for publishing and querying for statements contain
339 # syntactic sugar to easily let you specify apps that are known by multiple
340 # certificates.)
341 # REQUIRED
342 &quot;sha256Fingerprint&quot;: &quot;A String&quot;, # The uppercase SHA-265 fingerprint of the certificate. From the PEM
343 # certificate, it can be acquired like this:
344 #
345 # $ keytool -printcert -file $CERTFILE | grep SHA256:
346 # SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
347 # 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
348 #
349 # or like this:
350 #
351 # $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
352 # SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
353 # 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
354 #
355 # In this example, the contents of this field would be `14:6D:E9:83:C5:73:
356 # 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
357 # 44:E5`.
358 #
359 # If these tools are not available to you, you can convert the PEM
360 # certificate into the DER format, compute the SHA-256 hash of that string
361 # and represent the result as a hexstring (that is, uppercase hexadecimal
362 # representations of each octet, separated by colons).
363 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]364 },
365 },
366 &quot;relation&quot;: &quot;A String&quot;, # The relation identifies the use of the statement as intended by the source
367 # asset&#x27;s owner (that is, the person or entity who issued the statement).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]368 # Every complete statement has a relation.
369 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]370 # We identify relations with strings of the format `&lt;kind&gt;/&lt;detail&gt;`, where
371 # `&lt;kind&gt;` must be one of a set of pre-defined purpose categories, and
372 # `&lt;detail&gt;` is a free-form lowercase alphanumeric string that describes the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]373 # specific use case of the statement.
374 #
375 # Refer to [our API documentation](/digital-asset-links/v1/relation-strings)
376 # for the current list of supported relations.
377 #
378 # Example: `delegate_permission/common.handle_all_urls`
379 # REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]380 },
381 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]382 &quot;debugString&quot;: &quot;A String&quot;, # Human-readable message containing information intended to help end users
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]383 # understand, reproduce and debug the result.
384 #
385 #
386 # The message will be in English and we are currently not planning to offer
387 # any translations.
388 #
389 # Please note that no guarantees are made about the contents or format of
390 # this string. Any aspect of it may be subject to change without notice.
391 # You should not attempt to programmatically parse this data. For
392 # programmatic access, use the error_code field below.
Bu Sun Kim4ed7d3f2020-05-27 12:20:54 -0700[diff] [blame^]393 &quot;maxAge&quot;: &quot;A String&quot;, # From serving time, how much longer the response should be considered valid
394 # barring further updates.
395 # REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]396 }</pre>
397</div>
398
399</body></html>