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> <a 19 href="googleapiclient-module.html">Home</a> </th> 20 21 <!-- Tree link --> 22 <th> <a 23 href="module-tree.html">Trees</a> </th> 24 25 <!-- Index link --> 26 <th> <a 27 href="identifier-index.html">Indices</a> </th> 28 29 <!-- Help link --> 30 <th> <a 31 href="help.html">Help</a> </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 googleapiclient</a> :: 41 Module 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 private</a>]</span></td></tr> 49 <tr><td align="right"><span class="options" 50 >[<a href="frames.html" target="_top">frames</a 51 >] | <a href="googleapiclient.channel-module.html" 52 target="_top">no 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 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("https://example.com/my_web_hook") 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="some_bucket_id", 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()).execute() 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"> </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"> </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"> </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 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"> </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 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"> </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">*args</span>, 212 <span class="summary-sig-arg">**kwargs</span>)</span><br /> 213 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 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"> </span> 244 </td><td class="summary"> 245 <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> 246 </td> 247 </tr> 248<tr> 249 <td width="15%" align="right" valign="top" class="summary"> 250 <span class="summary-type"> </span> 251 </td><td class="summary"> 252 <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> 260 </td> 261 </tr> 262<tr> 263 <td width="15%" align="right" valign="top" class="summary"> 264 <span class="summary-type"> </span> 265 </td><td class="summary"> 266 <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> 267 </td> 268 </tr> 269<tr> 270 <td width="15%" align="right" valign="top" class="summary"> 271 <span class="summary-type"> </span> 272 </td><td class="summary"> 273 <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> 274 </td> 275 </tr> 276<tr> 277 <td width="15%" align="right" valign="top" class="summary"> 278 <span class="summary-type"> </span> 279 </td><td class="summary"> 280 <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> 281 </td> 282 </tr> 283<tr> 284 <td width="15%" align="right" valign="top" class="summary"> 285 <span class="summary-type"> </span> 286 </td><td class="summary"> 287 <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> 288 </td> 289 </tr> 290<tr> 291 <td width="15%" align="right" valign="top" class="summary"> 292 <span class="summary-type"> </span> 293 </td><td class="summary"> 294 <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"> </span> 300 </td><td class="summary"> 301 <a name="__package__"></a><span class="summary-name">__package__</span> = <code title="None">None</code> 302 </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 code</a></span> 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> 366 <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> 368 </h3> 369 </td><td align="right" valign="top" 370 ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source code</a></span> 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"> 431<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> 439</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> <a 451 href="googleapiclient-module.html">Home</a> </th> 452 453 <!-- Tree link --> 454 <th> <a 455 href="module-tree.html">Trees</a> </th> 456 457 <!-- Index link --> 458 <th> <a 459 href="identifier-index.html">Indices</a> </th> 460 461 <!-- Help link --> 462 <th> <a 463 href="help.html">Help</a> </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"> 471 Generated by Epydoc 3.0.1 on Fri Oct 2 20:46:22 2020 472 </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> 491