Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / dd49464a6262c0d1f71efcf11f131e2f591fe5f6 / . / docs / dyn / digitalassetlinks_v1.statements.html
blob: 9636a7c1b503da395dde6e74386e86215faf86af [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">
78 <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>
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">
82 <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>
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:
102 source_androidApp_packageName: string, Android App assets are naturally identified by their Java package name.
103For example, the Google Maps app uses the package name
104`com.google.android.apps.maps`.
105REQUIRED
106 relation: string, Use only associations that match the specified relation.
107
108See the [`Statement`](#Statement) message for a detailed definition of
109relation strings.
110
111For a query to match a statement, one of the following must be true:
112
113* both the query's and the statement's relation strings match exactly,
114 or
115* the query's relation string is empty or missing.
116
117Example: A query with relation `delegate_permission/common.handle_all_urls`
118matches an asset link with relation
119`delegate_permission/common.handle_all_urls`.
120 source_androidApp_certificate_sha256Fingerprint: string, The uppercase SHA-265 fingerprint of the certificate. From the PEM
121 certificate, it can be acquired like this:
122
123 $ keytool -printcert -file $CERTFILE | grep SHA256:
124 SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
125 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
126
127or like this:
128
129 $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
130 SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
131 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
132
133In this example, the contents of this field would be `14:6D:E9:83:C5:73:
13406:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
13544:E5`.
136
137If these tools are not available to you, you can convert the PEM
138certificate into the DER format, compute the SHA-256 hash of that string
139and represent the result as a hexstring (that is, uppercase hexadecimal
140representations of each octet, separated by colons).
141 x__xgafv: string, V1 error format.
142 Allowed values
143 1 - v1 error format
144 2 - v2 error format
145 source_web_site: string, Web assets are identified by a URL that contains only the scheme, hostname
146and port parts. The format is
147
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]148 http[s]://&lt;hostname&gt;[:&lt;port&gt;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]149
150Hostnames must be fully qualified: they must end in a single period
151("`.`").
152
153Only the schemes "http" and "https" are currently allowed.
154
155Port numbers are given as a decimal number, and they must be omitted if the
156standard port numbers are used: 80 for http and 443 for https.
157
158We call this limited URL the "site". All URLs that share the same scheme,
159hostname and port are considered to be a part of the site and thus belong
160to the web asset.
161
162Example: the asset with the site `https://www.google.com` contains all
163these URLs:
164
165 * `https://www.google.com/`
166 * `https://www.google.com:443/`
167 * `https://www.google.com/foo`
168 * `https://www.google.com/foo?bar`
169 * `https://www.google.com/foo#bar`
170 * `https://user@password:www.google.com/`
171
172But it does not contain these URLs:
173
174 * `http://www.google.com/` (wrong scheme)
175 * `https://google.com/` (hostname does not match)
176 * `https://www.google.com:444/` (port does not match)
177REQUIRED
178
179Returns:
180 An object of the form:
181
182 { # Response message for the List call.
183 "errorCode": [ # Error codes that describe the result of the List operation.
184 "A String",
185 ],
186 "statements": [ # A list of all the matching statements that have been found.
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).
196 "source": { # Uniquely identifies an asset. # Every statement has a source asset.
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.
202 "web": { # Describes a web asset. # Set if this is a web asset.
203 "site": "A String", # Web assets are identified by a URL that contains only the scheme, hostname
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
209 # ("`.`").
210 #
211 # Only the schemes "http" and "https" are currently allowed.
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 #
216 # We call this limited URL the "site". All URLs that share the same scheme,
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 },
237 "androidApp": { # Describes an android app asset. # Set if this is an Android App asset.
238 "packageName": "A String", # 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
242 "certificate": { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
243 # require a signing certificate, which in combination with the package name
244 # uniquely identifies an app.
245 #
246 # Some apps' signing keys are rotated, so they may be signed by different
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
257 "sha256Fingerprint": "A String", # The uppercase SHA-265 fingerprint of the certificate. From the PEM
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 },
281 "relation": "A String", # The relation identifies the use of the statement as intended by the source
282 # asset's owner (that is, the person or entity who issued the statement).
283 # Every complete statement has a relation.
284 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]285 # We identify relations with strings of the format `&lt;kind&gt;/&lt;detail&gt;`, where
286 # `&lt;kind&gt;` must be one of a set of pre-defined purpose categories, and
287 # `&lt;detail&gt;` is a free-form lowercase alphanumeric string that describes the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]288 # specific use case of the statement.
289 #
290 # Refer to [our API documentation](/digital-asset-links/v1/relation-strings)
291 # for the current list of supported relations.
292 #
293 # Example: `delegate_permission/common.handle_all_urls`
294 # REQUIRED
295 "target": { # Uniquely identifies an asset. # Every statement has a target asset.
296 # REQUIRED
297 #
298 # A digital asset is an identifiable and addressable online entity that
299 # typically provides some service or content. Examples of assets are websites,
300 # Android apps, Twitter feeds, and Plus Pages.
301 "web": { # Describes a web asset. # Set if this is a web asset.
302 "site": "A String", # Web assets are identified by a URL that contains only the scheme, hostname
303 # and port parts. The format is
304 #
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame^]305 # http[s]://&lt;hostname&gt;[:&lt;port&gt;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]306 #
307 # Hostnames must be fully qualified: they must end in a single period
308 # ("`.`").
309 #
310 # Only the schemes "http" and "https" are currently allowed.
311 #
312 # Port numbers are given as a decimal number, and they must be omitted if the
313 # standard port numbers are used: 80 for http and 443 for https.
314 #
315 # We call this limited URL the "site". All URLs that share the same scheme,
316 # hostname and port are considered to be a part of the site and thus belong
317 # to the web asset.
318 #
319 # Example: the asset with the site `https://www.google.com` contains all
320 # these URLs:
321 #
322 # * `https://www.google.com/`
323 # * `https://www.google.com:443/`
324 # * `https://www.google.com/foo`
325 # * `https://www.google.com/foo?bar`
326 # * `https://www.google.com/foo#bar`
327 # * `https://user@password:www.google.com/`
328 #
329 # But it does not contain these URLs:
330 #
331 # * `http://www.google.com/` (wrong scheme)
332 # * `https://google.com/` (hostname does not match)
333 # * `https://www.google.com:444/` (port does not match)
334 # REQUIRED
335 },
336 "androidApp": { # Describes an android app asset. # Set if this is an Android App asset.
337 "packageName": "A String", # Android App assets are naturally identified by their Java package name.
338 # For example, the Google Maps app uses the package name
339 # `com.google.android.apps.maps`.
340 # REQUIRED
341 "certificate": { # Describes an X509 certificate. # Because there is no global enforcement of package name uniqueness, we also
342 # require a signing certificate, which in combination with the package name
343 # uniquely identifies an app.
344 #
345 # Some apps' signing keys are rotated, so they may be signed by different
346 # keys over time. We treat these as distinct assets, since we use (package
347 # name, cert) as the unique ID. This should not normally pose any problems
348 # as both versions of the app will make the same or similar statements.
349 # Other assets making statements about the app will have to be updated when a
350 # key is rotated, however.
351 #
352 # (Note that the syntaxes for publishing and querying for statements contain
353 # syntactic sugar to easily let you specify apps that are known by multiple
354 # certificates.)
355 # REQUIRED
356 "sha256Fingerprint": "A String", # The uppercase SHA-265 fingerprint of the certificate. From the PEM
357 # certificate, it can be acquired like this:
358 #
359 # $ keytool -printcert -file $CERTFILE | grep SHA256:
360 # SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
361 # 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
362 #
363 # or like this:
364 #
365 # $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
366 # SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
367 # 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
368 #
369 # In this example, the contents of this field would be `14:6D:E9:83:C5:73:
370 # 06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
371 # 44:E5`.
372 #
373 # If these tools are not available to you, you can convert the PEM
374 # certificate into the DER format, compute the SHA-256 hash of that string
375 # and represent the result as a hexstring (that is, uppercase hexadecimal
376 # representations of each octet, separated by colons).
377 },
378 },
379 },
380 },
381 ],
382 "maxAge": "A String", # From serving time, how much longer the response should be considered valid
383 # barring further updates.
384 # REQUIRED
385 "debugString": "A String", # Human-readable message containing information intended to help end users
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>