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