"""Webex API wrappers.
Copyright (c) 2016-2024 Cisco and/or its affiliates.
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
"""
from webexpythonsdk.config import (
DEFAULT_BASE_URL,
DEFAULT_SINGLE_REQUEST_TIMEOUT,
DEFAULT_WAIT_ON_RATE_LIMIT,
)
from webexpythonsdk.environment import WEBEX_ACCESS_TOKEN
from webexpythonsdk.exceptions import AccessTokenError
from webexpythonsdk.models.immutable import immutable_data_factory
from webexpythonsdk.restsession import RestSession
from webexpythonsdk.utils import check_type
from .access_tokens import AccessTokensAPI
from .admin_audit_events import AdminAuditEventsAPI
from .attachment_actions import AttachmentActionsAPI
from .events import EventsAPI
from .guest_issuer import GuestIssuerAPI
from .licenses import LicensesAPI
from .memberships import MembershipsAPI
from .messages import MessagesAPI
from .organizations import OrganizationsAPI
from .people import PeopleAPI
from .roles import RolesAPI
from .rooms import RoomsAPI
from .room_tabs import RoomTabsAPI
from .recordings import RecordingsAPI
from .team_memberships import TeamMembershipsAPI
from .teams import TeamsAPI
from .webhooks import WebhooksAPI
from .meetings import MeetingsAPI
from .meeting_templates import MeetingTemplatesAPI
from .meeting_invitees import MeetingInviteesAPI
from .meeting_registrants import MeetingRegistrantsAPI
import os
[docs]
class WebexAPI(object):
"""Webex API wrapper.
Creates a 'session' for all API calls through a created WebexAPI
object. The 'session' handles authentication, provides the needed headers,
and checks all responses for error conditions.
WebexAPI wraps all of the individual Webex APIs and represents
them in a simple hierarchical structure.
"""
[docs]
def __init__(
self,
access_token=None,
base_url=DEFAULT_BASE_URL,
single_request_timeout=DEFAULT_SINGLE_REQUEST_TIMEOUT,
wait_on_rate_limit=DEFAULT_WAIT_ON_RATE_LIMIT,
object_factory=immutable_data_factory,
client_id=None,
client_secret=None,
oauth_code=None,
redirect_uri=None,
proxies=None,
be_geo_id=None,
caller=None,
disable_ssl_verify=False,
):
"""Create a new WebexAPI object.
An access token must be used when interacting with the Webex API.
This package supports three methods for you to provide that access
token:
1. You may manually specify the access token via the `access_token`
argument, when creating a new WebexAPI object.
2. If an access_token argument is not supplied, the package checks
for a WEBEX_ACCESS_TOKEN environment variable.
3. Provide the parameters (client_id, client_secret, oauth_code and
oauth_redirect_uri) from your oauth flow.
An AccessTokenError is raised if an access token is not provided
via one of these two methods.
Args:
access_token(str): The access token to be used for API
calls to the Webex service. Defaults to checking for a
WEBEX_ACCESS_TOKEN environment variable.
base_url(str): The base URL to be prefixed to the
individual API endpoint suffixes.
Defaults to webexpythonsdk.DEFAULT_BASE_URL.
single_request_timeout(int): Timeout (in seconds) for RESTful HTTP
requests. Defaults to
webexpythonsdk.config.DEFAULT_SINGLE_REQUEST_TIMEOUT.
wait_on_rate_limit(bool): Enables or disables automatic rate-limit
handling. Defaults to
webexpythonsdk.config.DEFAULT_WAIT_ON_RATE_LIMIT.
object_factory(callable): The factory function to use to create
Python objects from the returned Webex JSON data objects.
client_id(str): The client id of your integration. Provided
upon creation in the portal.
client_secret(str): The client secret of your integration.
Provided upon creation in the portal.
oauth_code(str): The oauth authorization code provided by
the user oauth process.
oauth_redirect_uri(str): The redirect URI used in the user
OAuth process.
proxies(dict): Dictionary of proxies passed on to the requests
session.
be_geo_id(str): Optional partner identifier for API usage
tracking. Defaults to checking for a BE_GEO_ID environment
variable.
caller(str): Optional identifier for API usage tracking.
Defaults to checking for a WEBEX_PYTHON_SDK_CALLER environment
variable.
disable_ssl_verify(bool): Optional boolean flag to disable ssl
verification. Defaults to False. If set to True, the requests
session won't verify ssl certs anymore.
Returns:
WebexAPI: A new WebexAPI object.
Raises:
TypeError: If the parameter types are incorrect.
AccessTokenError: If an access token is not provided via the
access_token argument or an environment variable.
"""
check_type(access_token, str, optional=True)
check_type(base_url, str, optional=True)
check_type(single_request_timeout, int, optional=True)
check_type(wait_on_rate_limit, bool, optional=True)
check_type(client_id, str, optional=True)
check_type(client_secret, str, optional=True)
check_type(oauth_code, str, optional=True)
check_type(redirect_uri, str, optional=True)
check_type(proxies, dict, optional=True)
check_type(be_geo_id, str, optional=True)
check_type(caller, str, optional=True)
check_type(disable_ssl_verify, bool, optional=True)
access_token = access_token or WEBEX_ACCESS_TOKEN
# Init AccessTokensAPI wrapper early to use for oauth requests
self.access_tokens = AccessTokensAPI(
base_url,
object_factory,
single_request_timeout=single_request_timeout,
)
# Check if the user has provided the required oauth parameters
oauth_param_list = [client_id, client_secret, oauth_code, redirect_uri]
if not access_token and all(oauth_param_list):
access_token = self.access_tokens.get(
client_id=client_id,
client_secret=client_secret,
code=oauth_code,
redirect_uri=redirect_uri,
).access_token
# Set optional API metrics tracking variables from env vars if there
be_geo_id = be_geo_id or os.environ.get("BE_GEO_ID")
caller = caller or os.environ.get("WEBEX_PYTHON_SDK_CALLER")
# If an access token hasn't been provided as a parameter, environment
# variable, or obtained via an OAuth exchange raise an error.
if not access_token:
raise AccessTokenError(
"You must provide a Webex access token to interact with "
"the Webex APIs, either via a WEBEX_ACCESS_TOKEN "
"environment variable or via the access_token argument."
)
# Create the API session
# All of the API calls associated with a WebexAPI object will
# leverage a single RESTful 'session' connecting to the Webex
# cloud.
self._session = RestSession(
access_token=access_token,
base_url=base_url,
single_request_timeout=single_request_timeout,
wait_on_rate_limit=wait_on_rate_limit,
proxies=proxies,
be_geo_id=be_geo_id,
caller=caller,
disable_ssl_verify=disable_ssl_verify,
)
# API wrappers
self.admin_audit_events = AdminAuditEventsAPI(
self._session,
object_factory,
)
self.attachment_actions = AttachmentActionsAPI(
self._session,
object_factory,
)
self.events = EventsAPI(self._session, object_factory)
self.guest_issuer = GuestIssuerAPI(self._session, object_factory)
self.licenses = LicensesAPI(self._session, object_factory)
self.memberships = MembershipsAPI(self._session, object_factory)
self.messages = MessagesAPI(self._session, object_factory)
self.organizations = OrganizationsAPI(self._session, object_factory)
self.people = PeopleAPI(self._session, object_factory)
self.roles = RolesAPI(self._session, object_factory)
self.rooms = RoomsAPI(self._session, object_factory)
self.room_tabs = RoomTabsAPI(self._session, object_factory)
self.teams = TeamsAPI(self._session, object_factory)
self.team_memberships = TeamMembershipsAPI(
self._session,
object_factory,
)
self.webhooks = WebhooksAPI(self._session, object_factory)
self.recordings = RecordingsAPI(self._session, object_factory)
self.meetings = MeetingsAPI(self._session, object_factory)
self.meeting_templates = MeetingTemplatesAPI(
self._session, object_factory
)
self.meeting_invitees = MeetingInviteesAPI(
self._session, object_factory
)
self.meeting_registrants = MeetingRegistrantsAPI(
self._session, object_factory
)
@property
def access_token(self):
"""The access token used for API calls to the Webex service."""
return self._session.access_token
@property
def base_url(self):
"""The base URL prefixed to the individual API endpoint suffixes."""
return self._session.base_url
@property
def single_request_timeout(self):
"""Timeout (in seconds) for an single HTTP request."""
return self._session.single_request_timeout
@property
def wait_on_rate_limit(self):
"""Automatic rate-limit handling enabled / disabled."""
return self._session.wait_on_rate_limit
# Create a class attribute for the Access Tokens API that can be accessed
# before WebexAPI object is initialized.
access_tokens = AccessTokensAPI(
base_url=DEFAULT_BASE_URL,
object_factory=immutable_data_factory,
single_request_timeout=DEFAULT_SINGLE_REQUEST_TIMEOUT,
)
[docs]
@classmethod
def from_oauth_code(cls, client_id, client_secret, code, redirect_uri):
"""Create a new WebexAPI connection object using an OAuth code.
Exchange an Authorization Code for an Access Token, then use the access
token to create a new WebexAPI connection object.
Args:
client_id(str): Provided when you created your integration.
client_secret(str): Provided when you created your
integration.
code(str): The Authorization Code provided by the user
OAuth process.
redirect_uri(str): The redirect URI used in the user OAuth
process.
Returns:
WebexAPI: A new WebexAPI object initialized with the
access token from the OAuth Authentication Code exchange.
Raises:
TypeError: If the parameter types are incorrect.
ApiError: If the Webex cloud returns an error.
"""
token_obj = cls.access_tokens.get(
client_id, client_secret, code, redirect_uri
)
return cls(access_token=token_obj.access_token)
[docs]
@classmethod
def from_oauth_refresh(cls, client_id, client_secret, refresh_token):
"""Create a new WebexAPI connection object using an OAuth refresh.
Exchange a refresh token for an Access Token, then use the access
token to create a new WebexAPI connection object.
Args:
client_id(str): Provided when you created your integration.
client_secret(str): Provided when you created your
integration.
refresh_token(str): Provided when you requested the Access
Token.
Returns:
WebexAPI: A new WebexAPI object initialized with the
access token from the OAuth Refresh Token exchange.
Raises:
TypeError: If the parameter types are incorrect.
ApiError: If the Webex cloud returns an error.
"""
token_obj = cls.access_tokens.refresh(
client_id, client_secret, refresh_token
)
return cls(access_token=token_obj.access_token)