Support statistics per aggregation unit (#373)

* Assign a unit name to any aggregation unit when sending messages

* Get statistics per unit

* Get number of units used this month

* Get name list of units used this month

* Update async_api.py

* modify sample based on lint error and warning

Author: Yang-33

README.rst

@@ -114,8 +114,8 @@ https://developers.line.biz/en/reference/messaging-api/#send-reply-message
 
     line_bot_api.reply_message(reply_token, TextSendMessage(text='Hello World!'))
 
-push\_message(self, to, messages, notification_disabled=False, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+push\_message(self, to, messages, notification_disabled=False, custom_aggregation_units=None, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Send messages to users, groups, and rooms at any time.
 
@@ -125,8 +125,8 @@ https://developers.line.biz/en/reference/messaging-api/#send-push-message
 
     line_bot_api.push_message(to, TextSendMessage(text='Hello World!'))
 
-multicast(self, to, messages, notification_disabled=False, timeout=None)
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+multicast(self, to, messages, notification_disabled=False, custom_aggregation_units=None, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Send push messages to multiple users at any time. Messages cannot be sent to groups or rooms.
 
@@ -590,8 +590,45 @@ https://developers.line.biz/en/reference/messaging-api/#get-message-event
     broadcast_response = line_bot_api.broadcast(TextSendMessage(text='Hello World!'))
     insight = line_bot_api.get_insight_message_event(broadcast_response.request_id)
     print(insight.overview)
-    
-get\_bot_info(self, timeout=None)
+
+get\_statistics\_per\_unit(self, custom_aggregation_unit, from_date, to_date, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Return statistics about how users interact with push and multicast messages.
+
+https://developers.line.biz/en/reference/partner-docs/#get-statistics-per-unit
+
+.. code:: python
+
+    unit_name = 'promotion_a'
+    line_bot_api.push_message('to', TextSendMessage(text='Hello World!'), custom_aggregation_units=unit_name)
+    insight = line_bot_api.get_statistics_per_unit(unit_name, '20210301', '20210331')
+    print(insight.overview)
+
+get\_number\_of\_units\_used\_this\_month(self, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Return the number of aggregation units used this month.
+
+https://developers.line.biz/en/reference/partner-docs/#get-number-of-units-used-this-month
+
+.. code:: python
+    usage = line_bot_api.get_number_of_units_used_this_month()
+    print(usage.num_of_custom_aggregation_units)
+
+get\_name\_list\_of\_units\_used\_this\_month(self, limit=100, start=None, timeout=None)
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Return the name list of units used this month for statistics aggregation.
+
+https://developers.line.biz/en/reference/partner-docs/#get-name-list-of-units-used-this-month
+
+.. code:: python
+    name_list = line_bot_api.get_name_list_of_units_used_this_month()
+    print(name_list.custom_aggregation_units)
+    print(name_list.next)
+
+get\_bot\_info(self, timeout=None)
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Get bot's basic information.

linebot/api.py

@@ -32,7 +32,9 @@
 )
 from .models.responses import (
     Group, UserIds, RichMenuAliasResponse, RichMenuAliasListResponse, ChannelAccessTokens,
-    IssueChannelTokenResponseV2, VerifyChannelTokenResponseV2, ValidAccessTokenKeyIDsResponse
+    IssueChannelTokenResponseV2, VerifyChannelTokenResponseV2, ValidAccessTokenKeyIDsResponse,
+    InsightMessageEventOfCustomAggregationUnitResponse, AggregationInfoResponse,
+    AggregationNameListResponse
 )
 
 
@@ -114,7 +116,8 @@ def reply_message(self, reply_token, messages, notification_disabled=False, time
 
     def push_message(
             self, to, messages,
-            retry_key=None, notification_disabled=False, timeout=None):
+            retry_key=None, notification_disabled=False,
+            custom_aggregation_units=None, timeout=None):
         """Call push message API.
 
         https://developers.line.biz/en/reference/messaging-api/#send-push-message
@@ -129,6 +132,11 @@ def push_message(
         :param retry_key: (optional) Arbitrarily generated UUID in hexadecimal notation.
         :param bool notification_disabled: (optional) True to disable push notification
             when the message is sent. The default value is False.
+        :param custom_aggregation_units: (optional) Name of aggregation unit. Case-sensitive.
+            Max unit: 1
+            Max aggregation unit name length: 30 characters
+            Supported character types: Half-width alphanumeric characters and underscore
+        :type custom_aggregation_units: str | list[str]
         :param timeout: (optional) How long to wait for the server
             to send data before giving up, as a float,
             or a (connect timeout, read timeout) float tuple.
@@ -147,11 +155,17 @@ def push_message(
             'notificationDisabled': notification_disabled,
         }
 
+        if custom_aggregation_units is not None:
+            if not isinstance(custom_aggregation_units, (list, tuple)):
+                custom_aggregation_units = [custom_aggregation_units]
+            data['customAggregationUnits'] = custom_aggregation_units
+
         self._post(
             '/v2/bot/message/push', data=json.dumps(data), timeout=timeout
         )
 
-    def multicast(self, to, messages, retry_key=None, notification_disabled=False, timeout=None):
+    def multicast(self, to, messages, retry_key=None, notification_disabled=False,
+                  custom_aggregation_units=None, timeout=None):
         """Call multicast API.
 
         https://developers.line.biz/en/reference/messaging-api/#send-multicast-message
@@ -169,6 +183,11 @@ def multicast(self, to, messages, retry_key=None, notification_disabled=False, t
         :param retry_key: (optional) Arbitrarily generated UUID in hexadecimal notation.
         :param bool notification_disabled: (optional) True to disable push notification
             when the message is sent. The default value is False.
+        :param custom_aggregation_units: (optional) Name of aggregation unit. Case-sensitive.
+            Max unit: 1
+            Max aggregation unit name length: 30 characters
+            Supported character types: Half-width alphanumeric characters and underscore
+        :type custom_aggregation_units: str | list[str]
         :param timeout: (optional) How long to wait for the server
             to send data before giving up, as a float,
             or a (connect timeout, read timeout) float tuple.
@@ -187,6 +206,11 @@ def multicast(self, to, messages, retry_key=None, notification_disabled=False, t
             'notificationDisabled': notification_disabled,
         }
 
+        if custom_aggregation_units is not None:
+            if not isinstance(custom_aggregation_units, (list, tuple)):
+                custom_aggregation_units = [custom_aggregation_units]
+            data['customAggregationUnits'] = custom_aggregation_units
+
         self._post(
             '/v2/bot/message/multicast', data=json.dumps(data), timeout=timeout
         )
@@ -1718,6 +1742,75 @@ def get_channel_token_key_ids_v2_1(
                              timeout=timeout)
         return ValidAccessTokenKeyIDsResponse.new_from_json_dict(response.json)
 
+    def get_statistics_per_unit(self, custom_aggregation_unit, from_date, to_date, timeout=None):
+        """Return statistics about how users interact with push and multicast messages.
+
+        https://developers.line.biz/en/reference/partner-docs/#get-statistics-per-unit
+
+        :param str custom_aggregation_unit: Name of aggregation unit specified when sending
+            the message like `push_message(...)` and `multicast(...)`.
+        :param str from_date: Start date of aggregation period.
+            The format is `yyyyMMdd` (Timezone is UTC+9).
+        :param str to_date: End date of aggregation period.
+            The end date can be specified for up to 30 days later.
+            The format is `yyyyMMdd` (Timezone is UTC+9).
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :rtype: :py:class:
+            `linebot.models.responses.InsightMessageEventOfCustomAggregationUnitResponse`
+        """
+        response = self._get(
+            '/v2/bot/insight/message/event/aggregation?'
+            'customAggregationUnit={custom_aggregation_unit}&from={from_date}&to={to_date}'.format(
+                custom_aggregation_unit=custom_aggregation_unit,
+                from_date=from_date, to_date=to_date),
+            timeout=timeout
+        )
+
+        return InsightMessageEventOfCustomAggregationUnitResponse.new_from_json_dict(response.json)
+
+    def get_number_of_units_used_this_month(self, timeout=None):
+        """Return the number of aggregation units used this month.
+
+        https://developers.line.biz/en/reference/partner-docs/#get-number-of-units-used-this-month
+
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :rtype: :py:class: `linebot.models.responses.AggregationInfoResponse`
+        """
+        response = self._get('/v2/bot/message/aggregation/info', timeout=timeout)
+        return AggregationInfoResponse.new_from_json_dict(response.json)
+
+    def get_name_list_of_units_used_this_month(self, limit=100, start=None, timeout=None):
+        """Return the name list of units used this month for statistics aggregation.
+
+        :param int limit: Maximum number of aggregation units you can get per request.
+            If you don't specify a value, or if you specify a value greater than or equal to 100,
+            the maximum is 100.
+        :param str start: Get the next array of name list of units
+        :param timeout: (optional) How long to wait for the server
+            to send data before giving up, as a float,
+            or a (connect timeout, read timeout) float tuple.
+            Default is self.http_client.timeout
+        :type timeout: float | tuple(float, float)
+        :rtype: :py:class: `linebot.models.responses.AggregationNameListResponse`
+        """
+        params = {'limit': limit} if start is None else {'limit': limit, 'start': start}
+
+        response = self._get(
+            '/v2/bot/message/aggregation/list',
+            params=params,
+            timeout=timeout
+        )
+
+        return AggregationNameListResponse.new_from_json_dict(response.json)
+
     def _get(self, path, endpoint=None, params=None, headers=None, stream=False, timeout=None):
         url = (endpoint or self.endpoint) + path