Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / b8458c0b73030155b64a3c2392b2f70e5fbc3baf / . / docs / dyn / digitalassetlinks_v1.statements.html
blob: 18c66ac1183b9d81ae02d5fac42d32c92f5224d6 [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;maxAge&quot;: &quot;A String&quot;, # From serving time, how much longer the response should be considered valid
184 # barring further updates.
185 # REQUIRED
186 &quot;errorCode&quot;: [ # Error codes that describe the result of the List operation.
187 &quot;A String&quot;,
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]188 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]189 &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]190 { # Describes a reliable statement that has been made about the relationship
191 # between a source asset and a target asset.
192 #
193 # Statements are always made by the source asset, either directly or by
194 # delegating to a statement list that is stored elsewhere.
195 #
196 # For more detailed definitions of statements and assets, please refer
197 # to our [API documentation landing
198 # page](/digital-asset-links/v1/getting-started).
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]199 &quot;target&quot;: { # Uniquely identifies an asset. # Every statement has a target asset.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]200 # REQUIRED
201 #
202 # A digital asset is an identifiable and addressable online entity that
203 # typically provides some service or content. Examples of assets are websites,
204 # Android apps, Twitter feeds, and Plus Pages.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]205 &quot;web&quot;: { # Describes a web asset. # Set if this is a web asset.
206 &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]207 # and port parts. The format is
208 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]209 # http[s]://&lt;hostname&gt;[:&lt;port&gt;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]210 #
211 # Hostnames must be fully qualified: they must end in a single period
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]212 # (&quot;`.`&quot;).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]213 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]214 # Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]215 #
216 # Port numbers are given as a decimal number, and they must be omitted if the
217 # standard port numbers are used: 80 for http and 443 for https.
218 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]219 # 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]220 # hostname and port are considered to be a part of the site and thus belong
221 # to the web asset.
222 #
223 # Example: the asset with the site `https://www.google.com` contains all
224 # these URLs:
225 #
226 # * `https://www.google.com/`
227 # * `https://www.google.com:443/`
228 # * `https://www.google.com/foo`
229 # * `https://www.google.com/foo?bar`
230 # * `https://www.google.com/foo#bar`
231 # * `https://user@password:www.google.com/`
232 #
233 # But it does not contain these URLs:
234 #
235 # * `http://www.google.com/` (wrong scheme)
236 # * `https://google.com/` (hostname does not match)
237 # * `https://www.google.com:444/` (port does not match)
238 # REQUIRED
239 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]240 &quot;androidApp&quot;: { # Describes an android app asset. # Set if this is an Android App asset.
241 &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]242 # require a signing certificate, which in combination with the package name
243 # uniquely identifies an app.
244 #
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]245 # 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]246 # keys over time. We treat these as distinct assets, since we use (package
247 # name, cert) as the unique ID. This should not normally pose any problems
248 # as both versions of the app will make the same or similar statements.
249 # Other assets making statements about the app will have to be updated when a
250 # key is rotated, however.
251 #
252 # (Note that the syntaxes for publishing and querying for statements contain
253 # syntactic sugar to easily let you specify apps that are known by multiple
254 # certificates.)
255 # REQUIRED
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]256 &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]257 # certificate, it can be acquired like this:
258 #
259 # $ keytool -printcert -file $CERTFILE | grep SHA256:
260 # SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
261 # 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
262 #
263 # or like this:
264 #
265 # $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
266 # SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
267 # 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
268 #
269 # In this example, the contents of this field would be `14:6D:E9:83:C5:73:
270 # 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
271 # 44:E5`.
272 #
273 # If these tools are not available to you, you can convert the PEM
274 # certificate into the DER format, compute the SHA-256 hash of that string
275 # and represent the result as a hexstring (that is, uppercase hexadecimal
276 # representations of each octet, separated by colons).
277 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]278 &quot;packageName&quot;: &quot;A String&quot;, # Android App assets are naturally identified by their Java package name.
279 # For example, the Google Maps app uses the package name
280 # `com.google.android.apps.maps`.
281 # REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]282 },
283 },
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]284 &quot;source&quot;: { # Uniquely identifies an asset. # Every statement has a source asset.
285 # REQUIRED
286 #
287 # A digital asset is an identifiable and addressable online entity that
288 # typically provides some service or content. Examples of assets are websites,
289 # Android apps, Twitter feeds, and Plus Pages.
290 &quot;web&quot;: { # Describes a web asset. # Set if this is a web asset.
291 &quot;site&quot;: &quot;A String&quot;, # Web assets are identified by a URL that contains only the scheme, hostname
292 # and port parts. The format is
293 #
294 # http[s]://&lt;hostname&gt;[:&lt;port&gt;]
295 #
296 # Hostnames must be fully qualified: they must end in a single period
297 # (&quot;`.`&quot;).
298 #
299 # Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
300 #
301 # Port numbers are given as a decimal number, and they must be omitted if the
302 # standard port numbers are used: 80 for http and 443 for https.
303 #
304 # We call this limited URL the &quot;site&quot;. All URLs that share the same scheme,
305 # hostname and port are considered to be a part of the site and thus belong
306 # to the web asset.
307 #
308 # Example: the asset with the site `https://www.google.com` contains all
309 # these URLs:
310 #
311 # * `https://www.google.com/`
312 # * `https://www.google.com:443/`
313 # * `https://www.google.com/foo`
314 # * `https://www.google.com/foo?bar`
315 # * `https://www.google.com/foo#bar`
316 # * `https://user@password:www.google.com/`
317 #
318 # But it does not contain these URLs:
319 #
320 # * `http://www.google.com/` (wrong scheme)
321 # * `https://google.com/` (hostname does not match)
322 # * `https://www.google.com:444/` (port does not match)
323 # REQUIRED
324 },
325 &quot;androidApp&quot;: { # Describes an android app asset. # Set if this is an Android App asset.
326 &quot;certificate&quot;: { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
327 # require a signing certificate, which in combination with the package name
328 # uniquely identifies an app.
329 #
330 # Some apps&#x27; signing keys are rotated, so they may be signed by different
331 # keys over time. We treat these as distinct assets, since we use (package
332 # name, cert) as the unique ID. This should not normally pose any problems
333 # as both versions of the app will make the same or similar statements.
334 # Other assets making statements about the app will have to be updated when a
335 # key is rotated, however.
336 #
337 # (Note that the syntaxes for publishing and querying for statements contain
338 # syntactic sugar to easily let you specify apps that are known by multiple
339 # certificates.)
340 # REQUIRED
341 &quot;sha256Fingerprint&quot;: &quot;A String&quot;, # The uppercase SHA-265 fingerprint of the certificate. From the PEM
342 # certificate, it can be acquired like this:
343 #
344 # $ keytool -printcert -file $CERTFILE | grep SHA256:
345 # SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
346 # 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
347 #
348 # or like this:
349 #
350 # $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
351 # SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
352 # 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
353 #
354 # In this example, the contents of this field would be `14:6D:E9:83:C5:73:
355 # 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
356 # 44:E5`.
357 #
358 # If these tools are not available to you, you can convert the PEM
359 # certificate into the DER format, compute the SHA-256 hash of that string
360 # and represent the result as a hexstring (that is, uppercase hexadecimal
361 # representations of each octet, separated by colons).
362 },
363 &quot;packageName&quot;: &quot;A String&quot;, # Android App assets are naturally identified by their Java package name.
364 # For example, the Google Maps app uses the package name
365 # `com.google.android.apps.maps`.
366 # REQUIRED
367 },
368 },
369 &quot;relation&quot;: &quot;A String&quot;, # The relation identifies the use of the statement as intended by the source
370 # 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]371 # Every complete statement has a relation.
372 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]373 # We identify relations with strings of the format `&lt;kind&gt;/&lt;detail&gt;`, where
374 # `&lt;kind&gt;` must be one of a set of pre-defined purpose categories, and
375 # `&lt;detail&gt;` is a free-form lowercase alphanumeric string that describes the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]376 # specific use case of the statement.
377 #
378 # Refer to [our API documentation](/digital-asset-links/v1/relation-strings)
379 # for the current list of supported relations.
380 #
381 # Example: `delegate_permission/common.handle_all_urls`
382 # REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]383 },
384 ],
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame]385 &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]386 # understand, reproduce and debug the result.
387 #
388 #
389 # The message will be in English and we are currently not planning to offer
390 # any translations.
391 #
392 # Please note that no guarantees are made about the contents or format of
393 # this string. Any aspect of it may be subject to change without notice.
394 # You should not attempt to programmatically parse this data. For
395 # programmatic access, use the error_code field below.
396 }</pre>
397</div>
398
399</body></html>