From 4a86a724b009a0406b7e7dd8c8c072f71e838359 Mon Sep 17 00:00:00 2001 From: Chris Caron Date: Wed, 3 Apr 2019 22:39:51 -0400 Subject: [PATCH] Microsoft Teams Notification Support; refs #94 --- README.md | 1 + apprise/plugins/NotifyMSTeams.py | 323 +++++++++++++++++++++++++++++++ test/test_rest_plugins.py | 71 +++++++ 3 files changed, 395 insertions(+) create mode 100644 apprise/plugins/NotifyMSTeams.py diff --git a/README.md b/README.md index fa6f7fd0..c32053d5 100644 --- a/README.md +++ b/README.md @@ -48,6 +48,7 @@ The table below identifies the services this tool supports and some example serv | [KODI](https://github.com/caronc/apprise/wiki/Notify_kodi) | kodi:// or kodis:// | (TCP) 8080 or 443 | kodi://hostname
kodi://user@hostname
kodi://user:password@hostname:port | [Matrix](https://github.com/caronc/apprise/wiki/Notify_matrix) | matrix:// or matrixs:// | (TCP) 80 or 443 | matrix://hostname
matrix://user@hostname
matrixs://user:pass@hostname:port/#room_alias
matrixs://user:pass@hostname:port/!room_id
matrixs://user:pass@hostname:port/#room_alias/!room_id/#room2
matrixs://token@hostname:port/?webhook=matrix
matrix://user:token@hostname/?webhook=slack&format=markdown | [Mattermost](https://github.com/caronc/apprise/wiki/Notify_mattermost) | mmost:// | (TCP) 8065 | mmost://hostname/authkey
mmost://hostname:80/authkey
mmost://user@hostname:80/authkey
mmost://hostname/authkey?channel=channel
mmosts://hostname/authkey
mmosts://user@hostname/authkey
+| [Microsoft Teams](https://github.com/caronc/apprise/wiki/Notify_msteams) | msteams:// | (TCP) 443 | msteams://TokenA/TokenB/TokenC/ | [Prowl](https://github.com/caronc/apprise/wiki/Notify_prowl) | prowl:// | (TCP) 443 | prowl://apikey
prowl://apikey/providerkey | [PushBullet](https://github.com/caronc/apprise/wiki/Notify_pushbullet) | pbul:// | (TCP) 443 | pbul://accesstoken
pbul://accesstoken/#channel
pbul://accesstoken/A_DEVICE_ID
pbul://accesstoken/email@address.com
pbul://accesstoken/#channel/#channel2/email@address.net/DEVICE | [Pushjet](https://github.com/caronc/apprise/wiki/Notify_pushjet) | pjet:// or pjets:// | (TCP) 80 or 443 | pjet://secret@hostname
pjet://secret@hostname:port
pjets://secret@hostname
pjets://secret@hostname:port diff --git a/apprise/plugins/NotifyMSTeams.py b/apprise/plugins/NotifyMSTeams.py new file mode 100644 index 00000000..a88ce4c9 --- /dev/null +++ b/apprise/plugins/NotifyMSTeams.py @@ -0,0 +1,323 @@ +# -*- coding: utf-8 -*- +# +# Copyright (C) 2019 Chris Caron +# All rights reserved. +# +# This code is licensed under the MIT License. +# +# 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. + +# To use this plugin, you need to create a webhook; you can read more about +# this here: +# https://dev.outlook.com/Connectors/\ +# GetStarted#creating-messages-through-office-365-connectors-\ +# in-microsoft-teams +# +# More details are here on API Construction: +# https://docs.microsoft.com/en-ca/outlook/actionable-messages/\ +# message-card-reference +# +# I personally created a free account at teams.microsoft.com and then +# went to the store (bottom left hand side of slack like interface). +# +# From here you can search for 'Incoming Webhook'. Once you click on it, +# you can associate the webhook with your team. At this point, you can +# optionally also assign it a name, an avatar. Finally you'll have to +# assign it a channel it will notify. +# +# When you've completed this, it will generate you a (webhook) URL that +# looks like: +# https://outlook.office.com/webhook/ \ +# abcdefgf8-2f4b-4eca-8f61-225c83db1967@abcdefg2-5a99-4849-8efc-\ +# c9e78d28e57d/IncomingWebhook/291289f63a8abd3593e834af4d79f9fe/\ +# a2329f43-0ffb-46ab-948b-c9abdad9d643 +# +# Yes... The URL is that big... But it looks like this (greatly simplified): +# https://outlook.office.com/webhook/ABCD/IncomingWebhook/DEFG/HIJK +# ^ ^ ^ +# | | | +# These are important <--------------^--------------------^----^ +# +# You'll notice that the first token is actually 2 separated by an @ symbol +# But lets just ignore that and assume it's one great big token instead. +# +# These 3 tokens is what you'll need to build your URL with: +# msteams://ABCD/DEFG/HIJK +# +import re +import requests +from json import dumps + +from .NotifyBase import NotifyBase +from ..common import NotifyImageSize +from ..common import NotifyType +from ..common import NotifyFormat +from ..utils import parse_bool + +# Used to prepare our UUID regex matching +UUID4_RE = \ + r'[0-9a-f]{8}-[0-9a-f]{4}-4[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}' +# r'[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}' + +# Token required as part of the API request +# /AAAAAAAAA@AAAAAAAAA/........./......... +VALIDATE_TOKEN_A = re.compile(r'{}@{}'.format(UUID4_RE, UUID4_RE), re.I) + +# Token required as part of the API request +# /................../BBBBBBBBB/.......... +VALIDATE_TOKEN_B = re.compile(r'[A-Za-z0-9]{32}') + +# Token required as part of the API request +# /........./........./CCCCCCCCCCCCCCCCCCCCCCCC +VALIDATE_TOKEN_C = re.compile(UUID4_RE, re.I) + + +class NotifyMSTeams(NotifyBase): + """ + A wrapper for Microsoft Teams Notifications + """ + + # The default descriptive name associated with the Notification + service_name = 'MSTeams' + + # The services URL + service_url = 'https://teams.micrsoft.com/' + + # The default secure protocol + secure_protocol = 'msteams' + + # A URL that takes you to the setup/help of the specific protocol + setup_url = 'https://github.com/caronc/apprise/wiki/Notify_msteams' + + # MSTeams uses the http protocol with JSON requests + notify_url = 'https://outlook.office.com/webhook' + + # Allows the user to specify the NotifyImageSize object + image_size = NotifyImageSize.XY_72 + + # The maximum allowable characters allowed in the body per message + body_maxlen = 1000 + + notify_format = NotifyFormat.MARKDOWN + + def __init__(self, token_a, token_b, token_c, include_image=True, + **kwargs): + """ + Initialize Microsoft Teams Object + """ + super(NotifyMSTeams, self).__init__(**kwargs) + + if not token_a: + msg = 'The first MSTeams API token is not specified.' + self.logger.warning(msg) + raise TypeError(msg) + + if not token_b: + msg = 'The second MSTeams API token is not specified.' + self.logger.warning(msg) + raise TypeError(msg) + + if not token_c: + msg = 'The third MSTeams API token is not specified.' + self.logger.warning(msg) + raise TypeError(msg) + + if not VALIDATE_TOKEN_A.match(token_a.strip()): + msg = 'The first MSTeams API token specified ({}) is invalid.'\ + .format(token_a) + self.logger.warning(msg) + raise TypeError(msg) + + # The token associated with the account + self.token_a = token_a.strip() + + if not VALIDATE_TOKEN_B.match(token_b.strip()): + msg = 'The second MSTeams API token specified ({}) is invalid.'\ + .format(token_b) + self.logger.warning(msg) + raise TypeError(msg) + + # The token associated with the account + self.token_b = token_b.strip() + + if not VALIDATE_TOKEN_C.match(token_c.strip()): + msg = 'The third MSTeams API token specified ({}) is invalid.'\ + .format(token_c) + self.logger.warning(msg) + raise TypeError(msg) + + # The token associated with the account + self.token_c = token_c.strip() + + # Place a thumbnail image inline with the message body + self.include_image = include_image + + def send(self, body, title='', notify_type=NotifyType.INFO, **kwargs): + """ + Perform Microsoft Teams Notification + """ + + headers = { + 'User-Agent': self.app_id, + 'Content-Type': 'application/json', + } + + url = '%s/%s/IncomingWebhook/%s/%s' % ( + self.notify_url, + self.token_a, + self.token_b, + self.token_c, + ) + + # Prepare our payload + payload = { + "@type": "MessageCard", + "@context": "https://schema.org/extensions", + "summary": self.app_desc, + "themeColor": self.color(notify_type), + "sections": [ + { + "activityImage": None, + "activityTitle": title, + "text": body, + }, + ] + } + + # Acquire our to-be footer icon if configured to do so + image_url = None if not self.include_image \ + else self.image_url(notify_type) + + if image_url: + payload['sections'][0]['activityImage'] = image_url + + self.logger.debug('MSTeams POST URL: %s (cert_verify=%r)' % ( + url, self.verify_certificate, + )) + self.logger.debug('MSTeams Payload: %s' % str(payload)) + + # Always call throttle before any remote server i/o is made + self.throttle() + try: + r = requests.post( + url, + data=dumps(payload), + headers=headers, + verify=self.verify_certificate, + ) + if r.status_code != requests.codes.ok: + # We had a problem + status_str = \ + NotifyMSTeams.http_response_code_lookup(r.status_code) + + self.logger.warning( + 'Failed to send MSTeams notification: ' + '{}{}error={}.'.format( + status_str, + ', ' if status_str else '', + r.status_code)) + + self.logger.debug( + 'Response Details:\r\n{}'.format(r.content)) + + # We failed + return False + + else: + self.logger.info('Sent MSTeams notification.') + + except requests.RequestException as e: + self.logger.warning( + 'A Connection error occured sending MSTeams notification.') + self.logger.debug('Socket Exception: %s' % str(e)) + + # We failed + return False + + return True + + def url(self): + """ + Returns the URL built dynamically based on specified arguments. + """ + + # Define any arguments set + args = { + 'format': self.notify_format, + 'overflow': self.overflow_mode, + 'image': 'yes' if self.include_image else 'no', + } + + return '{schema}://{token_a}/{token_b}/{token_c}/'\ + '?{args}'.format( + schema=self.secure_protocol, + token_a=NotifyMSTeams.quote(self.token_a, safe=''), + token_b=NotifyMSTeams.quote(self.token_b, safe=''), + token_c=NotifyMSTeams.quote(self.token_c, safe=''), + args=NotifyMSTeams.urlencode(args), + ) + + @staticmethod + def parse_url(url): + """ + Parses the URL and returns enough arguments that can allow + us to substantiate this object. + + """ + results = NotifyBase.parse_url(url, verify_host=False) + + if not results: + # We're done early as we couldn't load the results + return results + + # Get unquoted entries + entries = NotifyMSTeams.split_path(results['fullpath']) + + if results.get('user'): + # If a user was found, it's because it's still part of the first + # token, so we concatinate them + results['token_a'] = '{}@{}'.format( + NotifyMSTeams.unquote(results['user']), + NotifyMSTeams.unquote(results['host']), + ) + + else: + # The first token is stored in the hostname + results['token_a'] = NotifyMSTeams.unquote(results['host']) + + # Now fetch the remaining tokens + try: + results['token_b'] = entries.pop(0) + + except IndexError: + # We're done + results['token_b'] = None + + try: + results['token_c'] = entries.pop(0) + + except IndexError: + # We're done + results['token_c'] = None + + # Get Image + results['include_image'] = \ + parse_bool(results['qsd'].get('image', True)) + + return results diff --git a/test/test_rest_plugins.py b/test/test_rest_plugins.py index f63034cc..dcf9f5e1 100644 --- a/test/test_rest_plugins.py +++ b/test/test_rest_plugins.py @@ -43,6 +43,9 @@ from apprise.common import OverflowMode import logging logging.disable(logging.CRITICAL) +# a test UUID we can use +UUID4 = '8b799edf-6f98-4d3a-9be7-2862fb4e5752' + # Some exception handling we'll use REQUEST_EXCEPTIONS = ( requests.ConnectionError( @@ -932,6 +935,74 @@ TEST_URLS = ( 'test_requests_exceptions': True, }), + ################################## + # NotifyMSTeams + ################################## + ('msteams://', { + 'instance': None, + }), + ('msteams://:@/', { + # We don't have strict host checking on for msteams, so this URL + # actually becomes parseable and :@ becomes a hostname. + # The below errors because a second token wasn't found + 'instance': TypeError, + }), + ('msteams://{}'.format(UUID4), { + # Just half of one token 1 provided + 'instance': TypeError, + }), + ('msteams://{}@{}/'.format(UUID4, UUID4), { + # Just 1 tokens provided + 'instance': TypeError, + }), + ('msteams://{}@{}/{}'.format(UUID4, UUID4, 'a' * 32), { + # Just 2 tokens provided + 'instance': TypeError, + }), + ('msteams://{}@{}/{}/{}?ta'.format(UUID4, UUID4, 'a' * 20, UUID4), { + # All tokens provided - invalid token 2 + 'instance': TypeError, + }), + ('msteams://{}@{}/{}/{}?tb'.format(UUID4, UUID4, 'a' * 32, 'abcd'), { + # All tokens provided - invalid token 3 + 'instance': TypeError, + }), + ('msteams://{}@{}/{}/{}?tb'.format('garbage', UUID4, 'a' * 32, 'abcd'), { + # All tokens provided - invalid token 1 + 'instance': TypeError, + }), + ('msteams://{}@{}/{}/{}?t1'.format(UUID4, UUID4, 'a' * 32, UUID4), { + # All tokens provided - we're good + 'instance': plugins.NotifyMSTeams, + }), + ('msteams://{}@{}/{}/{}?t2'.format(UUID4, UUID4, 'a' * 32, UUID4), { + # All tokens provided - we're good + 'instance': plugins.NotifyMSTeams, + # don't include an image by default + 'include_image': False, + }), + ('msteams://{}@{}/{}/{}?image=No'.format(UUID4, UUID4, 'a' * 32, UUID4), { + # All tokens provided - we're good no image + 'instance': plugins.NotifyMSTeams, + }), + ('msteams://{}@{}/{}/{}?tx'.format(UUID4, UUID4, 'a' * 32, UUID4), { + 'instance': plugins.NotifyMSTeams, + # force a failure + 'response': False, + 'requests_response_code': requests.codes.internal_server_error, + }), + ('msteams://{}@{}/{}/{}?ty'.format(UUID4, UUID4, 'a' * 32, UUID4), { + 'instance': plugins.NotifyMSTeams, + # throw a bizzare code forcing us to fail to look it up + 'response': False, + 'requests_response_code': 999, + }), + ('msteams://{}@{}/{}/{}?tz'.format(UUID4, UUID4, 'a' * 32, UUID4), { + 'instance': plugins.NotifyMSTeams, + # Throws a series of connection and transfer exceptions when this flag + # is set and tests that we gracfully handle them + 'test_requests_exceptions': True, + }), ################################## # NotifyProwl