Package googleapiclient :: Module channel
[hide private]
[frames] | no frames]

Source Code for Module googleapiclient.channel

  1  # Copyright 2014 Google Inc. All Rights Reserved. 
  2  # 
  3  # Licensed under the Apache License, Version 2.0 (the "License"); 
  4  # you may not use this file except in compliance with the License. 
  5  # You may obtain a copy of the License at 
  6  # 
  7  #      http://www.apache.org/licenses/LICENSE-2.0 
  8  # 
  9  # Unless required by applicable law or agreed to in writing, software 
 10  # distributed under the License is distributed on an "AS IS" BASIS, 
 11  # WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 
 12  # See the License for the specific language governing permissions and 
 13  # limitations under the License. 
 14   
 15  """Channel notifications support. 
 16   
 17  Classes and functions to support channel subscriptions and notifications 
 18  on those channels. 
 19   
 20  Notes: 
 21    - This code is based on experimental APIs and is subject to change. 
 22    - Notification does not do deduplication of notification ids, that's up to 
 23      the receiver. 
 24    - Storing the Channel between calls is up to the caller. 
 25   
 26   
 27  Example setting up a channel: 
 28   
 29    # Create a new channel that gets notifications via webhook. 
 30    channel = new_webhook_channel("https://example.com/my_web_hook") 
 31   
 32    # Store the channel, keyed by 'channel.id'. Store it before calling the 
 33    # watch method because notifications may start arriving before the watch 
 34    # method returns. 
 35    ... 
 36   
 37    resp = service.objects().watchAll( 
 38      bucket="some_bucket_id", body=channel.body()).execute() 
 39    channel.update(resp) 
 40   
 41    # Store the channel, keyed by 'channel.id'. Store it after being updated 
 42    # since the resource_id value will now be correct, and that's needed to 
 43    # stop a subscription. 
 44    ... 
 45   
 46   
 47  An example Webhook implementation using webapp2. Note that webapp2 puts 
 48  headers in a case insensitive dictionary, as headers aren't guaranteed to 
 49  always be upper case. 
 50   
 51    id = self.request.headers[X_GOOG_CHANNEL_ID] 
 52   
 53    # Retrieve the channel by id. 
 54    channel = ... 
 55   
 56    # Parse notification from the headers, including validating the id. 
 57    n = notification_from_headers(channel, self.request.headers) 
 58   
 59    # Do app specific stuff with the notification here. 
 60    if n.resource_state == 'sync': 
 61      # Code to handle sync state. 
 62    elif n.resource_state == 'exists': 
 63      # Code to handle the exists state. 
 64    elif n.resource_state == 'not_exists': 
 65      # Code to handle the not exists state. 
 66   
 67   
 68  Example of unsubscribing. 
 69   
 70    service.channels().stop(channel.body()).execute() 
 71  """ 
 72  from __future__ import absolute_import 
 73   
 74  import datetime 
 75  import uuid 
 76   
 77  from googleapiclient import errors 
 78  from googleapiclient import _helpers as util 
 79  import six 
 80   
 81   
 82  # The unix time epoch starts at midnight 1970. 
 83  EPOCH = datetime.datetime.utcfromtimestamp(0) 
 84   
 85  # Map the names of the parameters in the JSON channel description to 
 86  # the parameter names we use in the Channel class. 
 87  CHANNEL_PARAMS = { 
 88      "address": "address", 
 89      "id": "id", 
 90      "expiration": "expiration", 
 91      "params": "params", 
 92      "resourceId": "resource_id", 
 93      "resourceUri": "resource_uri", 
 94      "type": "type", 
 95      "token": "token", 
 96  } 
 97   
 98  X_GOOG_CHANNEL_ID = "X-GOOG-CHANNEL-ID" 
 99  X_GOOG_MESSAGE_NUMBER = "X-GOOG-MESSAGE-NUMBER" 
100  X_GOOG_RESOURCE_STATE = "X-GOOG-RESOURCE-STATE" 
101  X_GOOG_RESOURCE_URI = "X-GOOG-RESOURCE-URI" 
102  X_GOOG_RESOURCE_ID = "X-GOOG-RESOURCE-ID" 
103 104 105 -def _upper_header_keys(headers):
106 new_headers = {} 107 for k, v in six.iteritems(headers): 108 new_headers[k.upper()] = v 109 return new_headers
110
111 112 -class Notification(object):
113 """A Notification from a Channel. 114 115 Notifications are not usually constructed directly, but are returned 116 from functions like notification_from_headers(). 117 118 Attributes: 119 message_number: int, The unique id number of this notification. 120 state: str, The state of the resource being monitored. 121 uri: str, The address of the resource being monitored. 122 resource_id: str, The unique identifier of the version of the resource at 123 this event. 124 """ 125 126 @util.positional(5)
127 - def __init__(self, message_number, state, resource_uri, resource_id):
128 """Notification constructor. 129 130 Args: 131 message_number: int, The unique id number of this notification. 132 state: str, The state of the resource being monitored. Can be one 133 of "exists", "not_exists", or "sync". 134 resource_uri: str, The address of the resource being monitored. 135 resource_id: str, The identifier of the watched resource. 136 """ 137 self.message_number = message_number 138 self.state = state 139 self.resource_uri = resource_uri 140 self.resource_id = resource_id
141
142 143 -class Channel(object):
144 """A Channel for notifications. 145 146 Usually not constructed directly, instead it is returned from helper 147 functions like new_webhook_channel(). 148 149 Attributes: 150 type: str, The type of delivery mechanism used by this channel. For 151 example, 'web_hook'. 152 id: str, A UUID for the channel. 153 token: str, An arbitrary string associated with the channel that 154 is delivered to the target address with each event delivered 155 over this channel. 156 address: str, The address of the receiving entity where events are 157 delivered. Specific to the channel type. 158 expiration: int, The time, in milliseconds from the epoch, when this 159 channel will expire. 160 params: dict, A dictionary of string to string, with additional parameters 161 controlling delivery channel behavior. 162 resource_id: str, An opaque id that identifies the resource that is 163 being watched. Stable across different API versions. 164 resource_uri: str, The canonicalized ID of the watched resource. 165 """ 166 167 @util.positional(5)
168 - def __init__( 169 self, 170 type, 171 id, 172 token, 173 address, 174 expiration=None, 175 params=None, 176 resource_id="", 177 resource_uri="", 178 ):
179 """Create a new Channel. 180 181 In user code, this Channel constructor will not typically be called 182 manually since there are functions for creating channels for each specific 183 type with a more customized set of arguments to pass. 184 185 Args: 186 type: str, The type of delivery mechanism used by this channel. For 187 example, 'web_hook'. 188 id: str, A UUID for the channel. 189 token: str, An arbitrary string associated with the channel that 190 is delivered to the target address with each event delivered 191 over this channel. 192 address: str, The address of the receiving entity where events are 193 delivered. Specific to the channel type. 194 expiration: int, The time, in milliseconds from the epoch, when this 195 channel will expire. 196 params: dict, A dictionary of string to string, with additional parameters 197 controlling delivery channel behavior. 198 resource_id: str, An opaque id that identifies the resource that is 199 being watched. Stable across different API versions. 200 resource_uri: str, The canonicalized ID of the watched resource. 201 """ 202 self.type = type 203 self.id = id 204 self.token = token 205 self.address = address 206 self.expiration = expiration 207 self.params = params 208 self.resource_id = resource_id 209 self.resource_uri = resource_uri
210
211 - def body(self):
212 """Build a body from the Channel. 213 214 Constructs a dictionary that's appropriate for passing into watch() 215 methods as the value of body argument. 216 217 Returns: 218 A dictionary representation of the channel. 219 """ 220 result = { 221 "id": self.id, 222 "token": self.token, 223 "type": self.type, 224 "address": self.address, 225 } 226 if self.params: 227 result["params"] = self.params 228 if self.resource_id: 229 result["resourceId"] = self.resource_id 230 if self.resource_uri: 231 result["resourceUri"] = self.resource_uri 232 if self.expiration: 233 result["expiration"] = self.expiration 234 235 return result
236
237 - def update(self, resp):
238 """Update a channel with information from the response of watch(). 239 240 When a request is sent to watch() a resource, the response returned 241 from the watch() request is a dictionary with updated channel information, 242 such as the resource_id, which is needed when stopping a subscription. 243 244 Args: 245 resp: dict, The response from a watch() method. 246 """ 247 for json_name, param_name in six.iteritems(CHANNEL_PARAMS): 248 value = resp.get(json_name) 249 if value is not None: 250 setattr(self, param_name, value)
251
252 253 -def notification_from_headers(channel, headers):
254 """Parse a notification from the webhook request headers, validate 255 the notification, and return a Notification object. 256 257 Args: 258 channel: Channel, The channel that the notification is associated with. 259 headers: dict, A dictionary like object that contains the request headers 260 from the webhook HTTP request. 261 262 Returns: 263 A Notification object. 264 265 Raises: 266 errors.InvalidNotificationError if the notification is invalid. 267 ValueError if the X-GOOG-MESSAGE-NUMBER can't be converted to an int. 268 """ 269 headers = _upper_header_keys(headers) 270 channel_id = headers[X_GOOG_CHANNEL_ID] 271 if channel.id != channel_id: 272 raise errors.InvalidNotificationError( 273 "Channel id mismatch: %s != %s" % (channel.id, channel_id) 274 ) 275 else: 276 message_number = int(headers[X_GOOG_MESSAGE_NUMBER]) 277 state = headers[X_GOOG_RESOURCE_STATE] 278 resource_uri = headers[X_GOOG_RESOURCE_URI] 279 resource_id = headers[X_GOOG_RESOURCE_ID] 280 return Notification(message_number, state, resource_uri, resource_id)
281
282 283 @util.positional(2) 284 -def new_webhook_channel(url, token=None, expiration=None, params=None):
285 """Create a new webhook Channel. 286 287 Args: 288 url: str, URL to post notifications to. 289 token: str, An arbitrary string associated with the channel that 290 is delivered to the target address with each notification delivered 291 over this channel. 292 expiration: datetime.datetime, A time in the future when the channel 293 should expire. Can also be None if the subscription should use the 294 default expiration. Note that different services may have different 295 limits on how long a subscription lasts. Check the response from the 296 watch() method to see the value the service has set for an expiration 297 time. 298 params: dict, Extra parameters to pass on channel creation. Currently 299 not used for webhook channels. 300 """ 301 expiration_ms = 0 302 if expiration: 303 delta = expiration - EPOCH 304 expiration_ms = ( 305 delta.microseconds / 1000 + (delta.seconds + delta.days * 24 * 3600) * 1000 306 ) 307 if expiration_ms < 0: 308 expiration_ms = 0 309 310 return Channel( 311 "web_hook", 312 str(uuid.uuid4()), 313 token, 314 url, 315 expiration=expiration_ms, 316 params=params, 317 )
318