Gitiles
Code Review Sign In
gerrit-public.fairphone.software / platform / external / python / google-api-python-client / 98b51f044ede8b9b24e584ab9680e3f35f4bd469 / . / docs / epy / googleapiclient.channel-module.html
blob: af1394f51b5c233657318530cd847e6b0bf4f6e0 [file] [log] [blame]
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]1<?xml version="1.0" encoding="ascii"?>
2<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
3 "DTD/xhtml1-transitional.dtd">
4<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
5<head>
6 <title>googleapiclient.channel</title>
7 <link rel="stylesheet" href="epydoc.css" type="text/css" />
8 <script type="text/javascript" src="epydoc.js"></script>
9</head>
10
11<body bgcolor="white" text="black" link="blue" vlink="#204080"
12 alink="#204080">
13<!-- ==================== NAVIGATION BAR ==================== -->
14<table class="navbar" border="0" width="100%" cellpadding="0"
15 bgcolor="#a0c0ff" cellspacing="0">
16 <tr valign="middle">
17 <!-- Home link -->
18 <th>&nbsp;&nbsp;&nbsp;<a
19 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
20
21 <!-- Tree link -->
22 <th>&nbsp;&nbsp;&nbsp;<a
23 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
24
25 <!-- Index link -->
26 <th>&nbsp;&nbsp;&nbsp;<a
27 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
28
29 <!-- Help link -->
30 <th>&nbsp;&nbsp;&nbsp;<a
31 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
32
33 <th class="navbar" width="100%"></th>
34 </tr>
35</table>
36<table width="100%" cellpadding="0" cellspacing="0">
37 <tr valign="top">
38 <td width="100%">
39 <span class="breadcrumbs">
40 <a href="googleapiclient-module.html">Package&nbsp;googleapiclient</a> ::
41 Module&nbsp;channel
42 </span>
43 </td>
44 <td>
45 <table cellpadding="0" cellspacing="0">
46 <!-- hide/show private -->
47 <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
48 onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
49 <tr><td align="right"><span class="options"
50 >[<a href="frames.html" target="_top">frames</a
51 >]&nbsp;|&nbsp;<a href="googleapiclient.channel-module.html"
52 target="_top">no&nbsp;frames</a>]</span></td></tr>
53 </table>
54 </td>
55 </tr>
56</table>
57<!-- ==================== MODULE DESCRIPTION ==================== -->
58<h1 class="epydoc">Module channel</h1><p class="nomargin-top"><span class="codelink"><a href="googleapiclient.channel-pysrc.html">source&nbsp;code</a></span></p>
59<pre class="literalblock">
60Channel notifications support.
61
62Classes and functions to support channel subscriptions and notifications
63on those channels.
64
65Notes:
66 - This code is based on experimental APIs and is subject to change.
67 - Notification does not do deduplication of notification ids, that's up to
68 the receiver.
69 - Storing the Channel between calls is up to the caller.
70
71
72Example setting up a channel:
73
74 # Create a new channel that gets notifications via webhook.
75 channel = new_webhook_channel(&quot;https://example.com/my_web_hook&quot;)
76
77 # Store the channel, keyed by 'channel.id'. Store it before calling the
78 # watch method because notifications may start arriving before the watch
79 # method returns.
80 ...
81
82 resp = service.objects().watchAll(
83 bucket=&quot;some_bucket_id&quot;, body=channel.body()).execute()
84 channel.update(resp)
85
86 # Store the channel, keyed by 'channel.id'. Store it after being updated
87 # since the resource_id value will now be correct, and that's needed to
88 # stop a subscription.
89 ...
90
91
92An example Webhook implementation using webapp2. Note that webapp2 puts
93headers in a case insensitive dictionary, as headers aren't guaranteed to
94always be upper case.
95
96 id = self.request.headers[X_GOOG_CHANNEL_ID]
97
98 # Retrieve the channel by id.
99 channel = ...
100
101 # Parse notification from the headers, including validating the id.
102 n = notification_from_headers(channel, self.request.headers)
103
104 # Do app specific stuff with the notification here.
105 if n.resource_state == 'sync':
106 # Code to handle sync state.
107 elif n.resource_state == 'exists':
108 # Code to handle the exists state.
109 elif n.resource_state == 'not_exists':
110 # Code to handle the not exists state.
111
112
113Example of unsubscribing.
114
115 service.channels().stop(channel.body())
116
117</pre>
118
119<!-- ==================== CLASSES ==================== -->
120<a name="section-Classes"></a>
121<table class="summary" border="1" cellpadding="3"
122 cellspacing="0" width="100%" bgcolor="white">
123<tr bgcolor="#70b0f0" class="table-header">
124 <td colspan="2" class="table-header">
125 <table border="0" cellpadding="0" cellspacing="0" width="100%">
126 <tr valign="top">
127 <td align="left"><span class="table-header">Classes</span></td>
128 <td align="right" valign="top"
129 ><span class="options">[<a href="#section-Classes"
130 class="privatelink" onclick="toggle_private();"
131 >hide private</a>]</span></td>
132 </tr>
133 </table>
134 </td>
135</tr>
136<tr>
137 <td width="15%" align="right" valign="top" class="summary">
138 <span class="summary-type">&nbsp;</span>
139 </td><td class="summary">
140 <a href="googleapiclient.channel.Notification-class.html" class="summary-name">Notification</a><br />
141 A Notification from a Channel.
142 </td>
143 </tr>
144<tr>
145 <td width="15%" align="right" valign="top" class="summary">
146 <span class="summary-type">&nbsp;</span>
147 </td><td class="summary">
148 <a href="googleapiclient.channel.Channel-class.html" class="summary-name">Channel</a><br />
149 A Channel for notifications.
150 </td>
151 </tr>
152</table>
153<!-- ==================== FUNCTIONS ==================== -->
154<a name="section-Functions"></a>
155<table class="summary" border="1" cellpadding="3"
156 cellspacing="0" width="100%" bgcolor="white">
157<tr bgcolor="#70b0f0" class="table-header">
158 <td colspan="2" class="table-header">
159 <table border="0" cellpadding="0" cellspacing="0" width="100%">
160 <tr valign="top">
161 <td align="left"><span class="table-header">Functions</span></td>
162 <td align="right" valign="top"
163 ><span class="options">[<a href="#section-Functions"
164 class="privatelink" onclick="toggle_private();"
165 >hide private</a>]</span></td>
166 </tr>
167 </table>
168 </td>
169</tr>
170<tr class="private">
171 <td width="15%" align="right" valign="top" class="summary">
172 <span class="summary-type">&nbsp;</span>
173 </td><td class="summary">
174 <table width="100%" cellpadding="0" cellspacing="0" border="0">
175 <tr>
176 <td><span class="summary-sig"><a name="_upper_header_keys"></a><span class="summary-sig-name">_upper_header_keys</span>(<span class="summary-sig-arg">headers</span>)</span></td>
177 <td align="right" valign="top">
178 <span class="codelink"><a href="googleapiclient.channel-pysrc.html#_upper_header_keys">source&nbsp;code</a></span>
179
180 </td>
181 </tr>
182 </table>
183
184 </td>
185 </tr>
186<tr>
187 <td width="15%" align="right" valign="top" class="summary">
188 <span class="summary-type">&nbsp;</span>
189 </td><td class="summary">
190 <table width="100%" cellpadding="0" cellspacing="0" border="0">
191 <tr>
192 <td><span class="summary-sig"><a href="googleapiclient.channel-module.html#notification_from_headers" class="summary-sig-name">notification_from_headers</a>(<span class="summary-sig-arg">channel</span>,
193 <span class="summary-sig-arg">headers</span>)</span><br />
194 Parse a notification from the webhook request headers, validate
195 the notification, and return a Notification object.</td>
196 <td align="right" valign="top">
197 <span class="codelink"><a href="googleapiclient.channel-pysrc.html#notification_from_headers">source&nbsp;code</a></span>
198
199 </td>
200 </tr>
201 </table>
202
203 </td>
204 </tr>
205<tr>
206 <td width="15%" align="right" valign="top" class="summary">
207 <span class="summary-type">&nbsp;</span>
208 </td><td class="summary">
209 <table width="100%" cellpadding="0" cellspacing="0" border="0">
210 <tr>
211 <td><span class="summary-sig"><a href="googleapiclient.channel-module.html#new_webhook_channel" class="summary-sig-name">new_webhook_channel</a>(<span class="summary-sig-arg">url</span>,
212 <span class="summary-sig-arg">token</span>=<span class="summary-sig-default">None</span>,
213 <span class="summary-sig-arg">expiration</span>=<span class="summary-sig-default">None</span>,
214 <span class="summary-sig-arg">params</span>=<span class="summary-sig-default">None</span>)</span><br />
215 Create a new webhook Channel.</td>
216 <td align="right" valign="top">
217 <span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>
218
219 </td>
220 </tr>
221 </table>
222
223 </td>
224 </tr>
225</table>
226<!-- ==================== VARIABLES ==================== -->
227<a name="section-Variables"></a>
228<table class="summary" border="1" cellpadding="3"
229 cellspacing="0" width="100%" bgcolor="white">
230<tr bgcolor="#70b0f0" class="table-header">
231 <td colspan="2" class="table-header">
232 <table border="0" cellpadding="0" cellspacing="0" width="100%">
233 <tr valign="top">
234 <td align="left"><span class="table-header">Variables</span></td>
235 <td align="right" valign="top"
236 ><span class="options">[<a href="#section-Variables"
237 class="privatelink" onclick="toggle_private();"
238 >hide private</a>]</span></td>
239 </tr>
240 </table>
241 </td>
242</tr>
243<tr>
244 <td width="15%" align="right" valign="top" class="summary">
245 <span class="summary-type">&nbsp;</span>
246 </td><td class="summary">
247 <a name="EPOCH"></a><span class="summary-name">EPOCH</span> = <code title="datetime.datetime.utcfromtimestamp(0)">datetime.datetime.utcfromtimestamp(0)</code>
248 </td>
249 </tr>
250<tr>
251 <td width="15%" align="right" valign="top" class="summary">
252 <span class="summary-type">&nbsp;</span>
253 </td><td class="summary">
254 <a href="googleapiclient.channel-module.html#CHANNEL_PARAMS" class="summary-name">CHANNEL_PARAMS</a> = <code title="{'address': 'address', 'id': 'id', 'expiration': 'expiration', 'params\
255': 'params', 'resourceId': 'resource_id', 'resourceUri': 'resource_uri\
256', 'type': 'type', 'token': 'token',}">{'address': 'address', 'id': 'id', 'expiratio<code class="variable-ellipsis">...</code></code>
257 </td>
258 </tr>
259<tr>
260 <td width="15%" align="right" valign="top" class="summary">
261 <span class="summary-type">&nbsp;</span>
262 </td><td class="summary">
263 <a name="X_GOOG_CHANNEL_ID"></a><span class="summary-name">X_GOOG_CHANNEL_ID</span> = <code title="'X-GOOG-CHANNEL-ID'">'X-GOOG-CHANNEL-ID'</code>
264 </td>
265 </tr>
266<tr>
267 <td width="15%" align="right" valign="top" class="summary">
268 <span class="summary-type">&nbsp;</span>
269 </td><td class="summary">
270 <a name="X_GOOG_MESSAGE_NUMBER"></a><span class="summary-name">X_GOOG_MESSAGE_NUMBER</span> = <code title="'X-GOOG-MESSAGE-NUMBER'">'X-GOOG-MESSAGE-NUMBER'</code>
271 </td>
272 </tr>
273<tr>
274 <td width="15%" align="right" valign="top" class="summary">
275 <span class="summary-type">&nbsp;</span>
276 </td><td class="summary">
277 <a name="X_GOOG_RESOURCE_STATE"></a><span class="summary-name">X_GOOG_RESOURCE_STATE</span> = <code title="'X-GOOG-RESOURCE-STATE'">'X-GOOG-RESOURCE-STATE'</code>
278 </td>
279 </tr>
280<tr>
281 <td width="15%" align="right" valign="top" class="summary">
282 <span class="summary-type">&nbsp;</span>
283 </td><td class="summary">
284 <a name="X_GOOG_RESOURCE_URI"></a><span class="summary-name">X_GOOG_RESOURCE_URI</span> = <code title="'X-GOOG-RESOURCE-URI'">'X-GOOG-RESOURCE-URI'</code>
285 </td>
286 </tr>
287<tr>
288 <td width="15%" align="right" valign="top" class="summary">
289 <span class="summary-type">&nbsp;</span>
290 </td><td class="summary">
291 <a name="X_GOOG_RESOURCE_ID"></a><span class="summary-name">X_GOOG_RESOURCE_ID</span> = <code title="'X-GOOG-RESOURCE-ID'">'X-GOOG-RESOURCE-ID'</code>
292 </td>
293 </tr>
294</table>
295<!-- ==================== FUNCTION DETAILS ==================== -->
296<a name="section-FunctionDetails"></a>
297<table class="details" border="1" cellpadding="3"
298 cellspacing="0" width="100%" bgcolor="white">
299<tr bgcolor="#70b0f0" class="table-header">
300 <td colspan="2" class="table-header">
301 <table border="0" cellpadding="0" cellspacing="0" width="100%">
302 <tr valign="top">
303 <td align="left"><span class="table-header">Function Details</span></td>
304 <td align="right" valign="top"
305 ><span class="options">[<a href="#section-FunctionDetails"
306 class="privatelink" onclick="toggle_private();"
307 >hide private</a>]</span></td>
308 </tr>
309 </table>
310 </td>
311</tr>
312</table>
313<a name="notification_from_headers"></a>
314<div>
315<table class="details" border="1" cellpadding="3"
316 cellspacing="0" width="100%" bgcolor="white">
317<tr><td>
318 <table width="100%" cellpadding="0" cellspacing="0" border="0">
319 <tr valign="top"><td>
320 <h3 class="epydoc"><span class="sig"><span class="sig-name">notification_from_headers</span>(<span class="sig-arg">channel</span>,
321 <span class="sig-arg">headers</span>)</span>
322 </h3>
323 </td><td align="right" valign="top"
324 ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#notification_from_headers">source&nbsp;code</a></span>&nbsp;
325 </td>
326 </tr></table>
327
328 <pre class="literalblock">
329Parse a notification from the webhook request headers, validate
330 the notification, and return a Notification object.
331
332Args:
333 channel: Channel, The channel that the notification is associated with.
334 headers: dict, A dictionary like object that contains the request headers
335 from the webhook HTTP request.
336
337Returns:
338 A Notification object.
339
340Raises:
341 errors.InvalidNotificationError if the notification is invalid.
342 ValueError if the X-GOOG-MESSAGE-NUMBER can't be converted to an int.
343
344</pre>
345 <dl class="fields">
346 </dl>
347</td></tr></table>
348</div>
349<a name="new_webhook_channel"></a>
350<div>
351<table class="details" border="1" cellpadding="3"
352 cellspacing="0" width="100%" bgcolor="white">
353<tr><td>
354 <table width="100%" cellpadding="0" cellspacing="0" border="0">
355 <tr valign="top"><td>
356 <h3 class="epydoc"><span class="sig"><span class="sig-name">new_webhook_channel</span>(<span class="sig-arg">url</span>,
357 <span class="sig-arg">token</span>=<span class="sig-default">None</span>,
358 <span class="sig-arg">expiration</span>=<span class="sig-default">None</span>,
359 <span class="sig-arg">params</span>=<span class="sig-default">None</span>)</span>
360 </h3>
361 </td><td align="right" valign="top"
362 ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>&nbsp;
363 </td>
364 </tr></table>
365
366 <pre class="literalblock">
367Create a new webhook Channel.
368
369Args:
370 url: str, URL to post notifications to.
371 token: str, An arbitrary string associated with the channel that
372 is delivered to the target address with each notification delivered
373 over this channel.
374 expiration: datetime.datetime, A time in the future when the channel
375 should expire. Can also be None if the subscription should use the
376 default expiration. Note that different services may have different
377 limits on how long a subscription lasts. Check the response from the
378 watch() method to see the value the service has set for an expiration
379 time.
380 params: dict, Extra parameters to pass on channel creation. Currently
381 not used for webhook channels.
382
383</pre>
384 <dl class="fields">
385 <dt>Decorators:</dt>
386 <dd><ul class="nomargin-top">
387 <li><code>@util.positional(2)</code></li>
388 </ul></dd>
389 </dl>
390</td></tr></table>
391</div>
392<br />
393<!-- ==================== VARIABLES DETAILS ==================== -->
394<a name="section-VariablesDetails"></a>
395<table class="details" border="1" cellpadding="3"
396 cellspacing="0" width="100%" bgcolor="white">
397<tr bgcolor="#70b0f0" class="table-header">
398 <td colspan="2" class="table-header">
399 <table border="0" cellpadding="0" cellspacing="0" width="100%">
400 <tr valign="top">
401 <td align="left"><span class="table-header">Variables Details</span></td>
402 <td align="right" valign="top"
403 ><span class="options">[<a href="#section-VariablesDetails"
404 class="privatelink" onclick="toggle_private();"
405 >hide private</a>]</span></td>
406 </tr>
407 </table>
408 </td>
409</tr>
410</table>
411<a name="CHANNEL_PARAMS"></a>
412<div>
413<table class="details" border="1" cellpadding="3"
414 cellspacing="0" width="100%" bgcolor="white">
415<tr><td>
416 <h3 class="epydoc">CHANNEL_PARAMS</h3>
417
418 <dl class="fields">
419 </dl>
420 <dl class="fields">
421 <dt>Value:</dt>
422 <dd><table><tr><td><pre class="variable">
423{'address': 'address', 'id': 'id', 'expiration': 'expiration', 'params<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
424': 'params', 'resourceId': 'resource_id', 'resourceUri': 'resource_uri<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
425', 'type': 'type', 'token': 'token',}
426</pre></td></tr></table>
427</dd>
428 </dl>
429</td></tr></table>
430</div>
431<br />
432<!-- ==================== NAVIGATION BAR ==================== -->
433<table class="navbar" border="0" width="100%" cellpadding="0"
434 bgcolor="#a0c0ff" cellspacing="0">
435 <tr valign="middle">
436 <!-- Home link -->
437 <th>&nbsp;&nbsp;&nbsp;<a
438 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
439
440 <!-- Tree link -->
441 <th>&nbsp;&nbsp;&nbsp;<a
442 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
443
444 <!-- Index link -->
445 <th>&nbsp;&nbsp;&nbsp;<a
446 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
447
448 <!-- Help link -->
449 <th>&nbsp;&nbsp;&nbsp;<a
450 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
451
452 <th class="navbar" width="100%"></th>
453 </tr>
454</table>
455<table border="0" cellpadding="0" cellspacing="0" width="100%%">
456 <tr>
457 <td align="left" class="footer">
Sai Cheemalapati4ba8c232017-06-06 18:46:08 -0400[diff] [blame]458 Generated by Epydoc 3.0.1 on Mon Jun 5 13:38:39 2017
John Asmuth614db982014-04-24 15:46:26 -0400[diff] [blame]459 </td>
460 <td align="right" class="footer">
461 <a target="mainFrame" href="http://epydoc.sourceforge.net"
462 >http://epydoc.sourceforge.net</a>
463 </td>
464 </tr>
465</table>
466
467<script type="text/javascript">
468 <!--
469 // Private objects are initially displayed (because if
470 // javascript is turned off then we want them to be
471 // visible); but by default, we want to hide them. So hide
472 // them unless we have a cookie that says to show them.
473 checkCookie();
474 // -->
475</script>
476</body>
477</html>