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">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 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"> </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"> </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"> </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"> </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"> </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"> </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"> </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 code</a></span> 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 code</a></span> 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> <a 438 href="googleapiclient-module.html">Home</a> </th> 439 440 <!-- Tree link --> 441 <th> <a 442 href="module-tree.html">Trees</a> </th> 443 444 <!-- Index link --> 445 <th> <a 446 href="identifier-index.html">Indices</a> </th> 447 448 <!-- Help link --> 449 <th> <a 450 href="help.html">Help</a> </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"> 458 Generated by Epydoc 3.0.1 on Fri Jun 14 15:57:27 2019 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> 478
