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