blob: cc6b3c7f18d342dbb5d3d25e972cf28fc7ecbae8 [file] [log] [blame]
John Asmuth614db982014-04-24 15:46:26 -04001<?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
Bu Sun Kim715bd7f2019-06-14 16:50:42 -0700115 service.channels().stop(channel.body()).execute()
John Asmuth614db982014-04-24 15:46:26 -0400116
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>
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700211 <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">*args</span>,
212 <span class="summary-sig-arg">**kwargs</span>)</span><br />
John Asmuth614db982014-04-24 15:46:26 -0400213 Create a new webhook Channel.</td>
214 <td align="right" valign="top">
215 <span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>
216
217 </td>
218 </tr>
219 </table>
220
221 </td>
222 </tr>
223</table>
224<!-- ==================== VARIABLES ==================== -->
225<a name="section-Variables"></a>
226<table class="summary" border="1" cellpadding="3"
227 cellspacing="0" width="100%" bgcolor="white">
228<tr bgcolor="#70b0f0" class="table-header">
229 <td colspan="2" class="table-header">
230 <table border="0" cellpadding="0" cellspacing="0" width="100%">
231 <tr valign="top">
232 <td align="left"><span class="table-header">Variables</span></td>
233 <td align="right" valign="top"
234 ><span class="options">[<a href="#section-Variables"
235 class="privatelink" onclick="toggle_private();"
236 >hide private</a>]</span></td>
237 </tr>
238 </table>
239 </td>
240</tr>
241<tr>
242 <td width="15%" align="right" valign="top" class="summary">
243 <span class="summary-type">&nbsp;</span>
244 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700245 <a name="EPOCH"></a><span class="summary-name">EPOCH</span> = <code title="datetime.datetime(1970, 1, 1, 0, 0)">datetime.datetime(1970, 1, 1, 0, 0)</code>
John Asmuth614db982014-04-24 15:46:26 -0400246 </td>
247 </tr>
248<tr>
249 <td width="15%" align="right" valign="top" class="summary">
250 <span class="summary-type">&nbsp;</span>
251 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700252 <a href="googleapiclient.channel-module.html#CHANNEL_PARAMS" class="summary-name">CHANNEL_PARAMS</a> = <code title="{'address': 'address',
253 'expiration': 'expiration',
254 'id': 'id',
255 'params': 'params',
256 'resourceId': 'resource_id',
257 'resourceUri': 'resource_uri',
258 'token': 'token',
259 'type': 'type'}"><code class="variable-group">{</code><code class="variable-quote">'</code><code class="variable-string">address</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">address</code><code class="variable-quote">'</code><code class="variable-op">, </code><code class="variable-quote">'</code><code class="variable-string">expiration</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">expirat</code><code class="variable-ellipsis">...</code></code>
John Asmuth614db982014-04-24 15:46:26 -0400260 </td>
261 </tr>
262<tr>
263 <td width="15%" align="right" valign="top" class="summary">
264 <span class="summary-type">&nbsp;</span>
265 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700266 <a name="X_GOOG_CHANNEL_ID"></a><span class="summary-name">X_GOOG_CHANNEL_ID</span> = <code title="'X-GOOG-CHANNEL-ID'"><code class="variable-quote">'</code><code class="variable-string">X-GOOG-CHANNEL-ID</code><code class="variable-quote">'</code></code>
John Asmuth614db982014-04-24 15:46:26 -0400267 </td>
268 </tr>
269<tr>
270 <td width="15%" align="right" valign="top" class="summary">
271 <span class="summary-type">&nbsp;</span>
272 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700273 <a name="X_GOOG_MESSAGE_NUMBER"></a><span class="summary-name">X_GOOG_MESSAGE_NUMBER</span> = <code title="'X-GOOG-MESSAGE-NUMBER'"><code class="variable-quote">'</code><code class="variable-string">X-GOOG-MESSAGE-NUMBER</code><code class="variable-quote">'</code></code>
John Asmuth614db982014-04-24 15:46:26 -0400274 </td>
275 </tr>
276<tr>
277 <td width="15%" align="right" valign="top" class="summary">
278 <span class="summary-type">&nbsp;</span>
279 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700280 <a name="X_GOOG_RESOURCE_STATE"></a><span class="summary-name">X_GOOG_RESOURCE_STATE</span> = <code title="'X-GOOG-RESOURCE-STATE'"><code class="variable-quote">'</code><code class="variable-string">X-GOOG-RESOURCE-STATE</code><code class="variable-quote">'</code></code>
John Asmuth614db982014-04-24 15:46:26 -0400281 </td>
282 </tr>
283<tr>
284 <td width="15%" align="right" valign="top" class="summary">
285 <span class="summary-type">&nbsp;</span>
286 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700287 <a name="X_GOOG_RESOURCE_URI"></a><span class="summary-name">X_GOOG_RESOURCE_URI</span> = <code title="'X-GOOG-RESOURCE-URI'"><code class="variable-quote">'</code><code class="variable-string">X-GOOG-RESOURCE-URI</code><code class="variable-quote">'</code></code>
John Asmuth614db982014-04-24 15:46:26 -0400288 </td>
289 </tr>
290<tr>
291 <td width="15%" align="right" valign="top" class="summary">
292 <span class="summary-type">&nbsp;</span>
293 </td><td class="summary">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700294 <a name="X_GOOG_RESOURCE_ID"></a><span class="summary-name">X_GOOG_RESOURCE_ID</span> = <code title="'X-GOOG-RESOURCE-ID'"><code class="variable-quote">'</code><code class="variable-string">X-GOOG-RESOURCE-ID</code><code class="variable-quote">'</code></code>
295 </td>
296 </tr>
297<tr>
298 <td width="15%" align="right" valign="top" class="summary">
299 <span class="summary-type">&nbsp;</span>
300 </td><td class="summary">
301 <a name="__package__"></a><span class="summary-name">__package__</span> = <code title="None">None</code>
John Asmuth614db982014-04-24 15:46:26 -0400302 </td>
303 </tr>
304</table>
305<!-- ==================== FUNCTION DETAILS ==================== -->
306<a name="section-FunctionDetails"></a>
307<table class="details" border="1" cellpadding="3"
308 cellspacing="0" width="100%" bgcolor="white">
309<tr bgcolor="#70b0f0" class="table-header">
310 <td colspan="2" class="table-header">
311 <table border="0" cellpadding="0" cellspacing="0" width="100%">
312 <tr valign="top">
313 <td align="left"><span class="table-header">Function Details</span></td>
314 <td align="right" valign="top"
315 ><span class="options">[<a href="#section-FunctionDetails"
316 class="privatelink" onclick="toggle_private();"
317 >hide private</a>]</span></td>
318 </tr>
319 </table>
320 </td>
321</tr>
322</table>
323<a name="notification_from_headers"></a>
324<div>
325<table class="details" border="1" cellpadding="3"
326 cellspacing="0" width="100%" bgcolor="white">
327<tr><td>
328 <table width="100%" cellpadding="0" cellspacing="0" border="0">
329 <tr valign="top"><td>
330 <h3 class="epydoc"><span class="sig"><span class="sig-name">notification_from_headers</span>(<span class="sig-arg">channel</span>,
331 <span class="sig-arg">headers</span>)</span>
332 </h3>
333 </td><td align="right" valign="top"
334 ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#notification_from_headers">source&nbsp;code</a></span>&nbsp;
335 </td>
336 </tr></table>
337
338 <pre class="literalblock">
339Parse a notification from the webhook request headers, validate
340 the notification, and return a Notification object.
341
342Args:
343 channel: Channel, The channel that the notification is associated with.
344 headers: dict, A dictionary like object that contains the request headers
345 from the webhook HTTP request.
346
347Returns:
348 A Notification object.
349
350Raises:
351 errors.InvalidNotificationError if the notification is invalid.
352 ValueError if the X-GOOG-MESSAGE-NUMBER can't be converted to an int.
353
354</pre>
355 <dl class="fields">
356 </dl>
357</td></tr></table>
358</div>
359<a name="new_webhook_channel"></a>
360<div>
361<table class="details" border="1" cellpadding="3"
362 cellspacing="0" width="100%" bgcolor="white">
363<tr><td>
364 <table width="100%" cellpadding="0" cellspacing="0" border="0">
365 <tr valign="top"><td>
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700366 <h3 class="epydoc"><span class="sig"><span class="sig-name">new_webhook_channel</span>(<span class="sig-arg">*args</span>,
367 <span class="sig-arg">**kwargs</span>)</span>
John Asmuth614db982014-04-24 15:46:26 -0400368 </h3>
369 </td><td align="right" valign="top"
370 ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>&nbsp;
371 </td>
372 </tr></table>
373
374 <pre class="literalblock">
375Create a new webhook Channel.
376
377Args:
378 url: str, URL to post notifications to.
379 token: str, An arbitrary string associated with the channel that
380 is delivered to the target address with each notification delivered
381 over this channel.
382 expiration: datetime.datetime, A time in the future when the channel
383 should expire. Can also be None if the subscription should use the
384 default expiration. Note that different services may have different
385 limits on how long a subscription lasts. Check the response from the
386 watch() method to see the value the service has set for an expiration
387 time.
388 params: dict, Extra parameters to pass on channel creation. Currently
389 not used for webhook channels.
390
391</pre>
392 <dl class="fields">
393 <dt>Decorators:</dt>
394 <dd><ul class="nomargin-top">
395 <li><code>@util.positional(2)</code></li>
396 </ul></dd>
397 </dl>
398</td></tr></table>
399</div>
400<br />
401<!-- ==================== VARIABLES DETAILS ==================== -->
402<a name="section-VariablesDetails"></a>
403<table class="details" border="1" cellpadding="3"
404 cellspacing="0" width="100%" bgcolor="white">
405<tr bgcolor="#70b0f0" class="table-header">
406 <td colspan="2" class="table-header">
407 <table border="0" cellpadding="0" cellspacing="0" width="100%">
408 <tr valign="top">
409 <td align="left"><span class="table-header">Variables Details</span></td>
410 <td align="right" valign="top"
411 ><span class="options">[<a href="#section-VariablesDetails"
412 class="privatelink" onclick="toggle_private();"
413 >hide private</a>]</span></td>
414 </tr>
415 </table>
416 </td>
417</tr>
418</table>
419<a name="CHANNEL_PARAMS"></a>
420<div>
421<table class="details" border="1" cellpadding="3"
422 cellspacing="0" width="100%" bgcolor="white">
423<tr><td>
424 <h3 class="epydoc">CHANNEL_PARAMS</h3>
425
426 <dl class="fields">
427 </dl>
428 <dl class="fields">
429 <dt>Value:</dt>
430 <dd><table><tr><td><pre class="variable">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700431<code class="variable-group">{</code><code class="variable-quote">'</code><code class="variable-string">address</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">address</code><code class="variable-quote">'</code><code class="variable-op">,</code>
432 <code class="variable-quote">'</code><code class="variable-string">expiration</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">expiration</code><code class="variable-quote">'</code><code class="variable-op">,</code>
433 <code class="variable-quote">'</code><code class="variable-string">id</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">id</code><code class="variable-quote">'</code><code class="variable-op">,</code>
434 <code class="variable-quote">'</code><code class="variable-string">params</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">params</code><code class="variable-quote">'</code><code class="variable-op">,</code>
435 <code class="variable-quote">'</code><code class="variable-string">resourceId</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">resource_id</code><code class="variable-quote">'</code><code class="variable-op">,</code>
436 <code class="variable-quote">'</code><code class="variable-string">resourceUri</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">resource_uri</code><code class="variable-quote">'</code><code class="variable-op">,</code>
437 <code class="variable-quote">'</code><code class="variable-string">token</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">token</code><code class="variable-quote">'</code><code class="variable-op">,</code>
438 <code class="variable-quote">'</code><code class="variable-string">type</code><code class="variable-quote">'</code><code class="variable-op">: </code><code class="variable-quote">'</code><code class="variable-string">type</code><code class="variable-quote">'</code><code class="variable-group">}</code>
John Asmuth614db982014-04-24 15:46:26 -0400439</pre></td></tr></table>
440</dd>
441 </dl>
442</td></tr></table>
443</div>
444<br />
445<!-- ==================== NAVIGATION BAR ==================== -->
446<table class="navbar" border="0" width="100%" cellpadding="0"
447 bgcolor="#a0c0ff" cellspacing="0">
448 <tr valign="middle">
449 <!-- Home link -->
450 <th>&nbsp;&nbsp;&nbsp;<a
451 href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>
452
453 <!-- Tree link -->
454 <th>&nbsp;&nbsp;&nbsp;<a
455 href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>
456
457 <!-- Index link -->
458 <th>&nbsp;&nbsp;&nbsp;<a
459 href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
460
461 <!-- Help link -->
462 <th>&nbsp;&nbsp;&nbsp;<a
463 href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
464
465 <th class="navbar" width="100%"></th>
466 </tr>
467</table>
468<table border="0" cellpadding="0" cellspacing="0" width="100%%">
469 <tr>
470 <td align="left" class="footer">
Dmitry Frenkel3e17f892020-10-06 16:46:05 -0700471 Generated by Epydoc 3.0.1 on Fri Oct 2 20:46:22 2020
John Asmuth614db982014-04-24 15:46:26 -0400472 </td>
473 <td align="right" class="footer">
474 <a target="mainFrame" href="http://epydoc.sourceforge.net"
475 >http://epydoc.sourceforge.net</a>
476 </td>
477 </tr>
478</table>
479
480<script type="text/javascript">
481 <!--
482 // Private objects are initially displayed (because if
483 // javascript is turned off then we want them to be
484 // visible); but by default, we want to hide them. So hide
485 // them unless we have a cookie that says to show them.
486 checkCookie();
487 // -->
488</script>
489</body>
490</html>