Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / 650209194f8080f37a5f20846931790f4c70ed46 / . / docs / dyn / digitalassetlinks_v1.assetlinks.html
blob: 7808023c05c210d436f9e4f7467deebbf527b7b7 [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.assetlinks.html">assetlinks</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="#check">check(target_androidApp_packageName=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, relation=None, target_web_site=None, target_androidApp_certificate_sha256Fingerprint=None, SHA256=None, source_androidApp_packageName=None, source_web_site=None, x__xgafv=None)</a></code></p>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]79<p class="firstline">Determines whether the specified (directional) relationship exists between</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="check">check(target_androidApp_packageName=None, source_androidApp_certificate_sha256Fingerprint=None, SHA256=None, relation=None, target_web_site=None, target_androidApp_certificate_sha256Fingerprint=None, SHA256=None, source_androidApp_packageName=None, source_web_site=None, x__xgafv=None)</code>
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]83 <pre>Determines whether the specified (directional) relationship exists between
84the specified source and target assets.
85
86The relation describes the intent of the link between the two assets as
87claimed by the source asset. An example for such relationships is the
88delegation of privileges or permissions.
89
90This command is most often used by infrastructure systems to check
91preconditions for an action. For example, a client may want to know if it
92is OK to send a web URL to a particular mobile app instead. The client can
93check for the relevant asset link from the website to the mobile app to
94decide if the operation should be allowed.
95
96A note about security: if you specify a secure asset as the source, such as
97an HTTPS website or an Android app, the API will ensure that any
98statements used to generate the response have been made in a secure way by
99the owner of that asset. Conversely, if the source asset is an insecure
100HTTP website (that is, the URL starts with `http://` instead of
101`https://`), the API cannot verify its statements securely, and it is not
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]102possible to ensure that the website&#x27;s statements have not been altered by a
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]103third party. For more information, see the [Digital Asset Links technical
104design
105specification](https://github.com/google/digitalassetlinks/blob/master/well-known/details.md).
106
107Args:
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]108 target_androidApp_packageName: string, Android App assets are naturally identified by their Java package name.
109For example, the Google Maps app uses the package name
110`com.google.android.apps.maps`.
111REQUIRED
112 source_androidApp_certificate_sha256Fingerprint: string, The uppercase SHA-265 fingerprint of the certificate. From the PEM
113 certificate, it can be acquired like this:
114
115 $ keytool -printcert -file $CERTFILE | grep SHA256:
116 SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
117 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
118
119or like this:
120
121 $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
122 SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
123 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
124
125In this example, the contents of this field would be `14:6D:E9:83:C5:73:
12606:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
12744:E5`.
128
129If these tools are not available to you, you can convert the PEM
130certificate into the DER format, compute the SHA-256 hash of that string
131and represent the result as a hexstring (that is, uppercase hexadecimal
132representations of each octet, separated by colons).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]133 relation: string, Query string for the relation.
134
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]135We identify relations with strings of the format `&lt;kind&gt;/&lt;detail&gt;`, where
136`&lt;kind&gt;` must be one of a set of pre-defined purpose categories, and
137`&lt;detail&gt;` is a free-form lowercase alphanumeric string that describes the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]138specific use case of the statement.
139
140Refer to [our API documentation](/digital-asset-links/v1/relation-strings)
141for the current list of supported relations.
142
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]143For a query to match an asset link, both the query&#x27;s and the asset link&#x27;s
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]144relation strings must match exactly.
145
146Example: A query with relation `delegate_permission/common.handle_all_urls`
147matches an asset link with relation
148`delegate_permission/common.handle_all_urls`.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]149 target_web_site: string, Web assets are identified by a URL that contains only the scheme, hostname
150and port parts. The format is
151
152 http[s]://&lt;hostname&gt;[:&lt;port&gt;]
153
154Hostnames must be fully qualified: they must end in a single period
155(&quot;`.`&quot;).
156
157Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
158
159Port numbers are given as a decimal number, and they must be omitted if the
160standard port numbers are used: 80 for http and 443 for https.
161
162We call this limited URL the &quot;site&quot;. All URLs that share the same scheme,
163hostname and port are considered to be a part of the site and thus belong
164to the web asset.
165
166Example: the asset with the site `https://www.google.com` contains all
167these URLs:
168
169 * `https://www.google.com/`
170 * `https://www.google.com:443/`
171 * `https://www.google.com/foo`
172 * `https://www.google.com/foo?bar`
173 * `https://www.google.com/foo#bar`
174 * `https://user@password:www.google.com/`
175
176But it does not contain these URLs:
177
178 * `http://www.google.com/` (wrong scheme)
179 * `https://google.com/` (hostname does not match)
180 * `https://www.google.com:444/` (port does not match)
181REQUIRED
182 target_androidApp_certificate_sha256Fingerprint: string, The uppercase SHA-265 fingerprint of the certificate. From the PEM
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]183 certificate, it can be acquired like this:
184
185 $ keytool -printcert -file $CERTFILE | grep SHA256:
186 SHA256: 14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83: \
187 42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
188
189or like this:
190
191 $ openssl x509 -in $CERTFILE -noout -fingerprint -sha256
192 SHA256 Fingerprint=14:6D:E9:83:C5:73:06:50:D8:EE:B9:95:2F:34:FC:64: \
193 16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:44:E5
194
195In this example, the contents of this field would be `14:6D:E9:83:C5:73:
19606:50:D8:EE:B9:95:2F:34:FC:64:16:A0:83:42:E6:1D:BE:A8:8A:04:96:B2:3F:CF:
19744:E5`.
198
199If these tools are not available to you, you can convert the PEM
200certificate into the DER format, compute the SHA-256 hash of that string
201and represent the result as a hexstring (that is, uppercase hexadecimal
202representations of each octet, separated by colons).
203 source_androidApp_packageName: string, Android App assets are naturally identified by their Java package name.
204For example, the Google Maps app uses the package name
205`com.google.android.apps.maps`.
206REQUIRED
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]207 source_web_site: string, Web assets are identified by a URL that contains only the scheme, hostname
208and port parts. The format is
209
Dan O'Mearadd494642020-05-01 07:42:23 -0700[diff] [blame]210 http[s]://&lt;hostname&gt;[:&lt;port&gt;]
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]211
212Hostnames must be fully qualified: they must end in a single period
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]213(&quot;`.`&quot;).
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]214
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]215Only the schemes &quot;http&quot; and &quot;https&quot; are currently allowed.
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]216
217Port numbers are given as a decimal number, and they must be omitted if the
218standard port numbers are used: 80 for http and 443 for https.
219
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]220We 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]221hostname and port are considered to be a part of the site and thus belong
222to the web asset.
223
224Example: the asset with the site `https://www.google.com` contains all
225these URLs:
226
227 * `https://www.google.com/`
228 * `https://www.google.com:443/`
229 * `https://www.google.com/foo`
230 * `https://www.google.com/foo?bar`
231 * `https://www.google.com/foo#bar`
232 * `https://user@password:www.google.com/`
233
234But it does not contain these URLs:
235
236 * `http://www.google.com/` (wrong scheme)
237 * `https://google.com/` (hostname does not match)
238 * `https://www.google.com:444/` (port does not match)
239REQUIRED
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]240 x__xgafv: string, V1 error format.
241 Allowed values
242 1 - v1 error format
243 2 - v2 error format
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]244
245Returns:
246 An object of the form:
247
248 { # Response message for the CheckAssetLinks call.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]249 &quot;linked&quot;: True or False, # Set to true if the assets specified in the request are linked by the
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]250 # relation specified in the request.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]251 &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]252 # understand, reproduce and debug the result.
253 #
254 #
255 # The message will be in English and we are currently not planning to offer
256 # any translations.
257 #
258 # Please note that no guarantees are made about the contents or format of
259 # this string. Any aspect of it may be subject to change without notice.
260 # You should not attempt to programmatically parse this data. For
261 # programmatic access, use the error_code field below.
Bu Sun Kim65020912020-05-20 12:08:20 -0700[diff] [blame^]262 &quot;maxAge&quot;: &quot;A String&quot;, # From serving time, how much longer the response should be considered valid
263 # barring further updates.
264 # REQUIRED
265 &quot;errorCode&quot;: [ # Error codes that describe the result of the Check operation.
266 &quot;A String&quot;,
267 ],
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700[diff] [blame]268 }</pre>
269</div>
270
271</body></html>