googleapiclient.channel

module documentation

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("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="some_bucket_id", 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()).execute()

Class	`Channel`	A Channel for notifications.
Class	`Notification`	A Notification from a Channel.
Function	`new_webhook_channel`	Create a new webhook Channel.
Function	`notification_from_headers`	the notification, and return a Notification object.
Constant	`CHANNEL_PARAMS`	Undocumented
Constant	`EPOCH`	Undocumented
Constant	`X_GOOG_CHANNEL_ID`	Undocumented
Constant	`X_GOOG_MESSAGE_NUMBER`	Undocumented
Constant	`X_GOOG_RESOURCE_ID`	Undocumented
Constant	`X_GOOG_RESOURCE_STATE`	Undocumented
Constant	`X_GOOG_RESOURCE_URI`	Undocumented
Function	`_upper_header_keys`	Undocumented

@util.positional(2)
def new_webhook_channel(url, token=None, expiration=None, params=None): ¶

Create a new webhook Channel.

Parameters
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.

def notification_from_headers(channel, headers): ¶

Parse a notification from the webhook request headers, validate: the notification, and return a Notification object.

Parameters
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.`

CHANNEL_PARAMS: dict[str, str] = ¶

Undocumented

Value

{'address': 'address',
 'id': 'id',
 'expiration': 'expiration',
 'params': 'params',
 'resourceId': 'resource_id',
 'resourceUri': 'resource_uri',
 'type': 'type',
...

EPOCH = ¶

Undocumented

Value

datetime.datetime(1970, 1, 1)

X_GOOG_CHANNEL_ID: str = ¶

Undocumented

Value

'X-GOOG-CHANNEL-ID'

X_GOOG_MESSAGE_NUMBER: str = ¶

Undocumented

Value

'X-GOOG-MESSAGE-NUMBER'

X_GOOG_RESOURCE_ID: str = ¶

Undocumented

Value

'X-GOOG-RESOURCE-ID'

X_GOOG_RESOURCE_STATE: str = ¶

Undocumented

Value

'X-GOOG-RESOURCE-STATE'

X_GOOG_RESOURCE_URI: str = ¶

Undocumented

Value

'X-GOOG-RESOURCE-URI'

def _upper_header_keys(headers): ¶

Undocumented