Merge pull request #90 from apivideo/sort-params-in-analytics

Add sort parameters in analytics routes

Author: bot-api-video

CHANGELOG.md

@@ -1,6 +1,9 @@
 # Changelog
 All changes to this project will be documented in this file.
 
+## [1.4.1] - 2024-09-05
+- Add sort parameters in analytics endpoints
+
 ## [1.4.0] - 2024-07-29
 - Add new analytics methods
 - Add livestream complete() method

docs/Api/AnalyticsApi.md

@@ -70,6 +70,8 @@ Name | Type | Description | Notes
 ------------- | ------------- | ------------- | ------------- 
  `from` | **\DateTime**| Use this query parameter to define the starting date-time of the period you want analytics for.  - If you do not set a value for `from`, the default assigned value is 1 day ago, based on the `to` parameter. - The maximum value is 30 days ago. - The value you provide should follow the ATOM date-time format: `2024-02-05T00:00:00+01:00` | [optional]
  `to` | **\DateTime**| Use this query parameter to define the ending date-time of the period you want analytics for.  - If you do not set a value for `to`, the default assigned value is `now`. - The value for `to` is a non-inclusive value: the API returns data **before** the date-time that you set. | [optional]
+ `sortBy` | **string**| Use this parameter to choose which field the API will use to sort the analytics data.  These are the available fields to sort by:  - `metricValue`: Sorts the results based on the **metric** you selected in your request. - `dimensionValue`: Sorts the results based on the **dimension** you selected in your request. | [optional]
+ `sortOrder` | **string**| Use this parameter to define the sort order of results.  These are the available sort orders:  - `asc`: Sorts the results in ascending order: `A to Z` and `0 to 9`. - `desc`: Sorts the results in descending order: `Z to A` and `9 to 0`. | [optional]
  `filterBy` | [**FilterBy2**](../Model/.md)| Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.  - If you do not set a value for `filterBy`, the API returns the full dataset for your project. - The API only accepts the `mediaId` and `mediaType` filters when you call `/data/metrics/play/total` or `/data/buckets/play-total/media-id`.  These are the available breakdown dimensions:  - `mediaId`: Returns analytics based on the unique identifiers of a video or a live stream. - `mediaType`: Returns analytics based on the type of content. Possible values: `video` and `live-stream`.  - `continent`: Returns analytics based on the viewers' continent. The list of supported continents names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `EU`. Possible values are: `AS`, `AF`, `NA`, `SA`, `AN`, `EU`, `AZ`.  - `country`: Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `FR`. - `deviceType`: Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`. - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. - `browser`: Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. - `tag`: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos [here](https://docs.api.video/vod/tags-metadata). | [optional]
  `currentPage` | **int**| Choose the number of search results to return per page. Minimum value: 1 | [optional] [default to 1]
  `pageSize` | **int**| Results per page. Allowed values 1-100, default is 25. | [optional] [default to 25]
@@ -109,6 +111,8 @@ Name | Type | Description | Notes
  `from` | **\DateTime**| Use this query parameter to define the starting date-time of the period you want analytics for.  - If you do not set a value for `from`, the default assigned value is 1 day ago, based on the `to` parameter. - The maximum value is 30 days ago. - The value you provide should follow the ATOM date-time format: `2024-02-05T00:00:00+01:00` | [optional]
  `to` | **\DateTime**| Use this query parameter to define the ending date-time of the period you want analytics for.  - If you do not set a value for `to`, the default assigned value is `now`. - The value for `to` is a non-inclusive value: the API returns data **before** the date-time that you set. | [optional]
  `interval` | **string**| Use this query parameter to define how granularity of the data. Possible values: `hour`, `day`.  - Default: If no interval specified and the period (different between from and to) ≤ 2 days then hour, otherwise day.  - If you do not set a value for `interval`, and the period you set using the `from` and `to` parameters is less than or equals to 2 days, then the default assigned value is `hour`. Otherwise the API sets it to `day`. | [optional]
+ `sortBy` | **string**| Use this parameter to choose which field the API will use to sort the analytics data.  These are the available fields to sort by:  - `metricValue`: Sorts the results based on the **metric** you selected in your request. - `emittedAt`: Sorts the results based on the **timestamp** of the event in ATOM date-time format. | [optional]
+ `sortOrder` | **string**| Use this parameter to define the sort order of results.  These are the available sort orders:  - `asc`: Sorts the results in ascending order: `A to Z` and `0 to 9`. - `desc`: Sorts the results in descending order: `Z to A` and `9 to 0`. | [optional]
  `filterBy` | [**FilterBy2**](../Model/.md)| Use this parameter to filter the API's response based on different data dimensions. You can serialize filters in your query to receive more detailed breakdowns of your analytics.  - If you do not set a value for `filterBy`, the API returns the full dataset for your project. - The API only accepts the `mediaId` and `mediaType` filters when you call `/data/metrics/play/total` or `/data/buckets/play-total/media-id`.  These are the available breakdown dimensions:  - `mediaId`: Returns analytics based on the unique identifiers of a video or a live stream. - `mediaType`: Returns analytics based on the type of content. Possible values: `video` and `live-stream`.  - `continent`: Returns analytics based on the viewers' continent. The list of supported continents names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `EU`. Possible values are: `AS`, `AF`, `NA`, `SA`, `AN`, `EU`, `AZ`.  - `country`: Returns analytics based on the viewers' country. The list of supported country names are based on the [GeoNames public database](https://www.geonames.org/countries/). You must use the ISO-3166 alpha2 format, for example `FR`. - `deviceType`: Returns analytics based on the type of device used by the viewers. Response values can include: `computer`, `phone`, `tablet`, `tv`, `console`, `wearable`, `unknown`. - `operatingSystem`: Returns analytics based on the operating system used by the viewers. Response values can include `windows`, `mac osx`, `android`, `ios`, `linux`. - `browser`: Returns analytics based on the browser used by the viewers. Response values can include `chrome`, `firefox`, `edge`, `opera`. - `tag`: Returns analytics for videos using this tag. This filter only accepts a single value and is case sensitive. Read more about tagging your videos [here](https://docs.api.video/vod/tags-metadata). | [optional]
  `currentPage` | **int**| Choose the number of search results to return per page. Minimum value: 1 | [optional] [default to 1]
  `pageSize` | **int**| Results per page. Allowed values 1-100, default is 25. | [optional] [default to 25]

src/Api/AnalyticsApi.php

@@ -193,6 +193,8 @@ private function buildGetMetricsBreakdownRequest(string $metric, string $breakdo
         // unbox the parameters from the associative array
         $from = array_key_exists('from', $queryParams) ? $queryParams['from'] : null;
         $to = array_key_exists('to', $queryParams) ? $queryParams['to'] : null;
+        $sortBy = array_key_exists('sortBy', $queryParams) ? $queryParams['sortBy'] : null;
+        $sortOrder = array_key_exists('sortOrder', $queryParams) ? $queryParams['sortOrder'] : null;
         $filterBy = array_key_exists('filterBy', $queryParams) ? $queryParams['filterBy'] : null;
         $currentPage = array_key_exists('currentPage', $queryParams) ? $queryParams['currentPage'] : 1;
         $pageSize = array_key_exists('pageSize', $queryParams) ? $queryParams['pageSize'] : 25;
@@ -233,6 +235,22 @@ private function buildGetMetricsBreakdownRequest(string $metric, string $breakdo
             $queryParams['to'] = $to;
         }
 
+        // sortBy query params
+        if (is_array($sortBy)) {
+            $sortBy = ObjectSerializer::serializeCollection($sortBy, 'form', true);
+        }
+        if ($sortBy !== null) {
+            $queryParams['sortBy'] = $sortBy;
+        }
+
+        // sortOrder query params
+        if (is_array($sortOrder)) {
+            $sortOrder = ObjectSerializer::serializeCollection($sortOrder, 'form', true);
+        }
+        if ($sortOrder !== null) {
+            $queryParams['sortOrder'] = $sortOrder;
+        }
+
         // filterBy query params
         if ($filterBy !== null) {
             if(is_array($filterBy)) {
@@ -320,6 +338,8 @@ private function buildGetMetricsOverTimeRequest(string $metric, array $queryPara
         $from = array_key_exists('from', $queryParams) ? $queryParams['from'] : null;
         $to = array_key_exists('to', $queryParams) ? $queryParams['to'] : null;
         $interval = array_key_exists('interval', $queryParams) ? $queryParams['interval'] : null;
+        $sortBy = array_key_exists('sortBy', $queryParams) ? $queryParams['sortBy'] : null;
+        $sortOrder = array_key_exists('sortOrder', $queryParams) ? $queryParams['sortOrder'] : null;
         $filterBy = array_key_exists('filterBy', $queryParams) ? $queryParams['filterBy'] : null;
         $currentPage = array_key_exists('currentPage', $queryParams) ? $queryParams['currentPage'] : 1;
         $pageSize = array_key_exists('pageSize', $queryParams) ? $queryParams['pageSize'] : 25;
@@ -362,6 +382,22 @@ private function buildGetMetricsOverTimeRequest(string $metric, array $queryPara
             $queryParams['interval'] = $interval;
         }
 
+        // sortBy query params
+        if (is_array($sortBy)) {
+            $sortBy = ObjectSerializer::serializeCollection($sortBy, 'form', true);
+        }
+        if ($sortBy !== null) {
+            $queryParams['sortBy'] = $sortBy;
+        }
+
+        // sortOrder query params
+        if (is_array($sortOrder)) {
+            $sortOrder = ObjectSerializer::serializeCollection($sortOrder, 'form', true);
+        }
+        if ($sortOrder !== null) {
+            $queryParams['sortOrder'] = $sortOrder;
+        }
+
         // filterBy query params
         if ($filterBy !== null) {
             if(is_array($filterBy)) {

src/BaseClient.php

@@ -78,7 +78,7 @@ public function __construct(string $baseUri, ?string $apiKey, ClientInterface $h
         $this->originSdkHeaderValue = "";
 
         if ($apiKey) {
-            $this->authenticator = new Authenticator($this, $apiKey, 'php:1.4.0');
+            $this->authenticator = new Authenticator($this, $apiKey, 'php:1.4.1');
         }
     }
 
@@ -111,7 +111,7 @@ public function request(Request $commandRequest, bool $skipAuthRequest = false):
         if($this->originSdkHeaderValue) {
             $request = $request->withHeader('AV-Origin-Sdk', $this->originSdkHeaderValue);
         }
-        $request = $request->withHeader('AV-Origin-Client', 'php:1.4.0');
+        $request = $request->withHeader('AV-Origin-Client', 'php:1.4.1');
 
         return $this->sendRequest($request, $skipAuthRequest);
     }