docs/epy/googleapiclient.channel-module.html

<?xml version="1.0" encoding="ascii"?>
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
          "DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
  <title>googleapiclient.channel</title>
  <link rel="stylesheet" href="epydoc.css" type="text/css" />
  <script type="text/javascript" src="epydoc.js"></script>
</head>

<body bgcolor="white" text="black" link="blue" vlink="#204080"
      alink="#204080">
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table width="100%" cellpadding="0" cellspacing="0">
  <tr valign="top">
    <td width="100%">
      <span class="breadcrumbs">
        <a href="googleapiclient-module.html">Package&nbsp;googleapiclient</a> ::
        Module&nbsp;channel
      </span>
    </td>
    <td>
      <table cellpadding="0" cellspacing="0">
        <!-- hide/show private -->
        <tr><td align="right"><span class="options">[<a href="javascript:void(0);" class="privatelink"
    onclick="toggle_private();">hide&nbsp;private</a>]</span></td></tr>
        <tr><td align="right"><span class="options"
            >[<a href="frames.html" target="_top">frames</a
            >]&nbsp;|&nbsp;<a href="googleapiclient.channel-module.html"
            target="_top">no&nbsp;frames</a>]</span></td></tr>
      </table>
    </td>
  </tr>
</table>
<!-- ==================== MODULE DESCRIPTION ==================== -->
<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>
<pre class="literalblock">
Channel notifications support.

Classes and functions to support channel subscriptions and notifications
on those channels.

Notes:
  - This code is based on experimental APIs and is subject to change.
  - Notification does not do deduplication of notification ids, that's up to
    the receiver.
  - Storing the Channel between calls is up to the caller.


Example setting up a channel:

  # Create a new channel that gets notifications via webhook.
  channel = new_webhook_channel(&quot;https://example.com/my_web_hook";)

  # Store the channel, keyed by 'channel.id'. Store it before calling the
  # watch method because notifications may start arriving before the watch
  # method returns.
  ...

  resp = service.objects().watchAll(
    bucket=&quot;some_bucket_id&quot;, body=channel.body()).execute()
  channel.update(resp)

  # Store the channel, keyed by 'channel.id'. Store it after being updated
  # since the resource_id value will now be correct, and that's needed to
  # stop a subscription.
  ...


An example Webhook implementation using webapp2. Note that webapp2 puts
headers in a case insensitive dictionary, as headers aren't guaranteed to
always be upper case.

  id = self.request.headers[X_GOOG_CHANNEL_ID]

  # Retrieve the channel by id.
  channel = ...

  # Parse notification from the headers, including validating the id.
  n = notification_from_headers(channel, self.request.headers)

  # Do app specific stuff with the notification here.
  if n.resource_state == 'sync':
    # Code to handle sync state.
  elif n.resource_state == 'exists':
    # Code to handle the exists state.
  elif n.resource_state == 'not_exists':
    # Code to handle the not exists state.


Example of unsubscribing.

  service.channels().stop(channel.body())

</pre>

<!-- ==================== CLASSES ==================== -->
<a name="section-Classes"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Classes</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Classes"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="googleapiclient.channel.Notification-class.html" class="summary-name">Notification</a><br />
      A Notification from a Channel.
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="googleapiclient.channel.Channel-class.html" class="summary-name">Channel</a><br />
      A Channel for notifications.
    </td>
  </tr>
</table>
<!-- ==================== FUNCTIONS ==================== -->
<a name="section-Functions"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Functions</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Functions"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr class="private">
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <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>
          <td align="right" valign="top">
            <span class="codelink"><a href="googleapiclient.channel-pysrc.html#_upper_header_keys">source&nbsp;code</a></span>

          </td>
        </tr>
      </table>

    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <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>,
        <span class="summary-sig-arg">headers</span>)</span><br />
      Parse a notification from the webhook request headers, validate
  the notification, and return a Notification object.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="googleapiclient.channel-pysrc.html#notification_from_headers">source&nbsp;code</a></span>

          </td>
        </tr>
      </table>

    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
      <table width="100%" cellpadding="0" cellspacing="0" border="0">
        <tr>
          <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>,
        <span class="summary-sig-arg">token</span>=<span class="summary-sig-default">None</span>,
        <span class="summary-sig-arg">expiration</span>=<span class="summary-sig-default">None</span>,
        <span class="summary-sig-arg">params</span>=<span class="summary-sig-default">None</span>)</span><br />
      Create a new webhook Channel.</td>
          <td align="right" valign="top">
            <span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>

          </td>
        </tr>
      </table>

    </td>
  </tr>
</table>
<!-- ==================== VARIABLES ==================== -->
<a name="section-Variables"></a>
<table class="summary" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Variables</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-Variables"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a name="EPOCH"></a><span class="summary-name">EPOCH</span> = <code title="datetime.datetime.utcfromtimestamp(0)">datetime.datetime.utcfromtimestamp(0)</code>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <a href="googleapiclient.channel-module.html#CHANNEL_PARAMS" class="summary-name">CHANNEL_PARAMS</a> = <code title="{'address': 'address', 'id': 'id', 'expiration': 'expiration', 'params\
': 'params', 'resourceId': 'resource_id', 'resourceUri': 'resource_uri\
', 'type': 'type', 'token': 'token',}">{'address': 'address', 'id': 'id', 'expiratio<code class="variable-ellipsis">...</code></code>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <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>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <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>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <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>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <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>
    </td>
  </tr>
<tr>
    <td width="15%" align="right" valign="top" class="summary">
      <span class="summary-type">&nbsp;</span>
    </td><td class="summary">
        <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>
    </td>
  </tr>
</table>
<!-- ==================== FUNCTION DETAILS ==================== -->
<a name="section-FunctionDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Function Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-FunctionDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="notification_from_headers"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">notification_from_headers</span>(<span class="sig-arg">channel</span>,
        <span class="sig-arg">headers</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#notification_from_headers">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>

  <pre class="literalblock">
Parse a notification from the webhook request headers, validate
  the notification, and return a Notification object.

Args:
  channel: Channel, The channel that the notification is associated with.
  headers: dict, A dictionary like object that contains the request headers
    from the webhook HTTP request.

Returns:
  A Notification object.

Raises:
  errors.InvalidNotificationError if the notification is invalid.
  ValueError if the X-GOOG-MESSAGE-NUMBER can't be converted to an int.

</pre>
  <dl class="fields">
  </dl>
</td></tr></table>
</div>
<a name="new_webhook_channel"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <table width="100%" cellpadding="0" cellspacing="0" border="0">
  <tr valign="top"><td>
  <h3 class="epydoc"><span class="sig"><span class="sig-name">new_webhook_channel</span>(<span class="sig-arg">url</span>,
        <span class="sig-arg">token</span>=<span class="sig-default">None</span>,
        <span class="sig-arg">expiration</span>=<span class="sig-default">None</span>,
        <span class="sig-arg">params</span>=<span class="sig-default">None</span>)</span>
  </h3>
  </td><td align="right" valign="top"
    ><span class="codelink"><a href="googleapiclient.channel-pysrc.html#new_webhook_channel">source&nbsp;code</a></span>&nbsp;
    </td>
  </tr></table>

  <pre class="literalblock">
Create a new webhook Channel.

Args:
  url: str, URL to post notifications to.
  token: str, An arbitrary string associated with the channel that
    is delivered to the target address with each notification delivered
    over this channel.
  expiration: datetime.datetime, A time in the future when the channel
    should expire. Can also be None if the subscription should use the
    default expiration. Note that different services may have different
    limits on how long a subscription lasts. Check the response from the
    watch() method to see the value the service has set for an expiration
    time.
  params: dict, Extra parameters to pass on channel creation. Currently
    not used for webhook channels.

</pre>
  <dl class="fields">
    <dt>Decorators:</dt>
    <dd><ul class="nomargin-top">
        <li><code>@util.positional(2)</code></li>
    </ul></dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== VARIABLES DETAILS ==================== -->
<a name="section-VariablesDetails"></a>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr bgcolor="#70b0f0" class="table-header">
  <td colspan="2" class="table-header">
    <table border="0" cellpadding="0" cellspacing="0" width="100%">
      <tr valign="top">
        <td align="left"><span class="table-header">Variables Details</span></td>
        <td align="right" valign="top"
         ><span class="options">[<a href="#section-VariablesDetails"
         class="privatelink" onclick="toggle_private();"
         >hide private</a>]</span></td>
      </tr>
    </table>
  </td>
</tr>
</table>
<a name="CHANNEL_PARAMS"></a>
<div>
<table class="details" border="1" cellpadding="3"
       cellspacing="0" width="100%" bgcolor="white">
<tr><td>
  <h3 class="epydoc">CHANNEL_PARAMS</h3>

  <dl class="fields">
  </dl>
  <dl class="fields">
    <dt>Value:</dt>
      <dd><table><tr><td><pre class="variable">
{'address': 'address', 'id': 'id', 'expiration': 'expiration', 'params<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
': 'params', 'resourceId': 'resource_id', 'resourceUri': 'resource_uri<span class="variable-linewrap"><img src="crarr.png" alt="\" /></span>
', 'type': 'type', 'token': 'token',}
</pre></td></tr></table>
</dd>
  </dl>
</td></tr></table>
</div>
<br />
<!-- ==================== NAVIGATION BAR ==================== -->
<table class="navbar" border="0" width="100%" cellpadding="0"
       bgcolor="#a0c0ff" cellspacing="0">
  <tr valign="middle">
  <!-- Home link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="googleapiclient-module.html">Home</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Tree link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="module-tree.html">Trees</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Index link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>

  <!-- Help link -->
      <th>&nbsp;&nbsp;&nbsp;<a
        href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>

      <th class="navbar" width="100%"></th>
  </tr>
</table>
<table border="0" cellpadding="0" cellspacing="0" width="100%%">
  <tr>
    <td align="left" class="footer">
    Generated by Epydoc 3.0.1 on Mon Jun  5 13:38:39 2017
    </td>
    <td align="right" class="footer">
      <a target="mainFrame" href="http://epydoc.sourceforge.net"
        >http://epydoc.sourceforge.net</a>
    </td>
  </tr>
</table>

<script type="text/javascript">
  <!--
  // Private objects are initially displayed (because if
  // javascript is turned off then we want them to be
  // visible); but by default, we want to hide them.  So hide
  // them unless we have a cookie that says to show them.
  checkCookie();
  // -->
</script>
</body>
</html>