From 6dfb0b6a03acde7688bae878a621e9a0b35a18ed Mon Sep 17 00:00:00 2001 From: Ondrej Fiedler Date: Mon, 11 Mar 2019 14:03:50 +0100 Subject: [PATCH] Add logic parameter to recommendation endpoints. Use HTTPS as default. --- README.md | 2 +- src/RecommApi/Client.php | 4 +-- .../Requests/RecommendItemsToItem.php | 36 +++++++++++++------ .../Requests/RecommendItemsToUser.php | 16 ++++++++- .../Requests/RecommendUsersToItem.php | 16 ++++++++- .../Requests/RecommendUsersToUser.php | 16 ++++++++- 6 files changed, 73 insertions(+), 17 deletions(-) diff --git a/README.md b/README.md index 534a556..ef26a71 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,7 @@ or ``` { "require": { - "recombee/php-api-client": "^2.3.0" + "recombee/php-api-client": "^2.4.0" } } ``` diff --git a/src/RecommApi/Client.php b/src/RecommApi/Client.php index 6ba2455..f11e428 100644 --- a/src/RecommApi/Client.php +++ b/src/RecommApi/Client.php @@ -40,7 +40,7 @@ class Client{ * @param string $protocol Default protocol for sending requests. Possible values: 'http', 'https'. * @param array $options Other custom options */ - public function __construct($account, $token, $protocol = 'http', $options= array()) { + public function __construct($account, $token, $protocol = 'https', $options= array()) { $this->account = $account; $this->token = $token; $this->protocol = $protocol; @@ -52,7 +52,7 @@ public function __construct($account, $token, $protocol = 'http', $options= arra } protected function getUserAgent() { - $user_agent = 'recombee-php-api-client/2.3.0'; + $user_agent = 'recombee-php-api-client/2.4.0'; if (isset($this->options['serviceName'])) $user_agent .= ' '.($this->options['serviceName']); return $user_agent; diff --git a/src/RecommApi/Requests/RecommendItemsToItem.php b/src/RecommApi/Requests/RecommendItemsToItem.php index 210f641..80dfd2a 100644 --- a/src/RecommApi/Requests/RecommendItemsToItem.php +++ b/src/RecommApi/Requests/RecommendItemsToItem.php @@ -40,10 +40,6 @@ class RecommendItemsToItem extends Request { * @var int $count Number of items to be recommended (N for the top-N recommendation). */ protected $count; - /** - * @var float $user_impact If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`. - */ - protected $user_impact; /** * @var string $filter Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes. */ @@ -60,6 +56,12 @@ class RecommendItemsToItem extends Request { * @var string $scenario Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. */ protected $scenario; + /** + * @var string| $logic Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. + */ + protected $logic; /** * @var bool $return_properties With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. * Example response: @@ -118,6 +120,10 @@ class RecommendItemsToItem extends Request { * ``` */ protected $included_properties; + /** + * @var float $user_impact **Expert option** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`. + */ + protected $user_impact; /** * @var float $diversity **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. */ @@ -166,9 +172,6 @@ class RecommendItemsToItem extends Request { * @param int $count Number of items to be recommended (N for the top-N recommendation). * @param array $optional Optional parameters given as an array containing pairs name of the parameter => value * - Allowed parameters: - * - *userImpact* - * - Type: float - * - Description: If *targetUserId* parameter is present, the recommendations are biased towards the user given. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`. * - *filter* * - Type: string * - Description: Boolean-returning [ReQL](https://docs.recombee.com/reql.html) expression which allows you to filter recommended items based on the values of their attributes. @@ -181,6 +184,11 @@ class RecommendItemsToItem extends Request { * - *scenario* * - Type: string * - Description: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. + * - *logic* + * - Type: string| + * - Description: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. * - *returnProperties* * - Type: bool * - Description: With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. @@ -237,6 +245,9 @@ class RecommendItemsToItem extends Request { * ] * } * ``` + * - *userImpact* + * - Type: float + * - Description: **Expert option** If *targetUserId* parameter is present, the recommendations are biased towards the given user. Using *userImpact*, you may control this bias. For an extreme case of `userImpact=0.0`, the interactions made by the user are not taken into account at all (with the exception of history-based blacklisting), for `userImpact=1.0`, you'll get user-based recommendation. The default value is `0`. * - *diversity* * - Type: float * - Description: **Expert option** Real number from [0.0, 1.0] which determines how much mutually dissimilar should the recommended items be. The default value is 0.0, i.e., no diversification. Value 1.0 means maximal diversification. @@ -261,13 +272,14 @@ public function __construct($item_id, $target_user_id, $count, $optional = array $this->item_id = $item_id; $this->target_user_id = $target_user_id; $this->count = $count; - $this->user_impact = isset($optional['userImpact']) ? $optional['userImpact'] : null; $this->filter = isset($optional['filter']) ? $optional['filter'] : null; $this->booster = isset($optional['booster']) ? $optional['booster'] : null; $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null; $this->scenario = isset($optional['scenario']) ? $optional['scenario'] : null; + $this->logic = isset($optional['logic']) ? $optional['logic'] : null; $this->return_properties = isset($optional['returnProperties']) ? $optional['returnProperties'] : null; $this->included_properties = isset($optional['includedProperties']) ? $optional['includedProperties'] : null; + $this->user_impact = isset($optional['userImpact']) ? $optional['userImpact'] : null; $this->diversity = isset($optional['diversity']) ? $optional['diversity'] : null; $this->min_relevance = isset($optional['minRelevance']) ? $optional['minRelevance'] : null; $this->rotation_rate = isset($optional['rotationRate']) ? $optional['rotationRate'] : null; @@ -276,7 +288,7 @@ public function __construct($item_id, $target_user_id, $count, $optional = array $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null; $this->optional = $optional; - $existing_optional = array('userImpact','filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); + $existing_optional = array('filter','booster','cascadeCreate','scenario','logic','returnProperties','includedProperties','userImpact','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); foreach ($this->optional as $key => $value) { if (!in_array($key, $existing_optional)) throw new UnknownOptionalParameterException($key); @@ -318,8 +330,6 @@ public function getBodyParameters() { $p = array(); $p['targetUserId'] = $this->target_user_id; $p['count'] = $this->count; - if (isset($this->optional['userImpact'])) - $p['userImpact'] = $this-> optional['userImpact']; if (isset($this->optional['filter'])) $p['filter'] = $this-> optional['filter']; if (isset($this->optional['booster'])) @@ -328,10 +338,14 @@ public function getBodyParameters() { $p['cascadeCreate'] = $this-> optional['cascadeCreate']; if (isset($this->optional['scenario'])) $p['scenario'] = $this-> optional['scenario']; + if (isset($this->optional['logic'])) + $p['logic'] = $this-> optional['logic']; if (isset($this->optional['returnProperties'])) $p['returnProperties'] = $this-> optional['returnProperties']; if (isset($this->optional['includedProperties'])) $p['includedProperties'] = $this-> optional['includedProperties']; + if (isset($this->optional['userImpact'])) + $p['userImpact'] = $this-> optional['userImpact']; if (isset($this->optional['diversity'])) $p['diversity'] = $this-> optional['diversity']; if (isset($this->optional['minRelevance'])) diff --git a/src/RecommApi/Requests/RecommendItemsToUser.php b/src/RecommApi/Requests/RecommendItemsToUser.php index 6fa39ba..3751d19 100644 --- a/src/RecommApi/Requests/RecommendItemsToUser.php +++ b/src/RecommApi/Requests/RecommendItemsToUser.php @@ -40,6 +40,12 @@ class RecommendItemsToUser extends Request { * @var string $scenario Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. */ protected $scenario; + /** + * @var string| $logic Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. + */ + protected $logic; /** * @var bool $return_properties With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. * Example response: @@ -145,6 +151,11 @@ class RecommendItemsToUser extends Request { * - *scenario* * - Type: string * - Description: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. + * - *logic* + * - Type: string| + * - Description: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. * - *returnProperties* * - Type: bool * - Description: With `returnProperties=true`, property values of the recommended items are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying of the recommended items to the user. @@ -228,6 +239,7 @@ public function __construct($user_id, $count, $optional = array()) { $this->booster = isset($optional['booster']) ? $optional['booster'] : null; $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null; $this->scenario = isset($optional['scenario']) ? $optional['scenario'] : null; + $this->logic = isset($optional['logic']) ? $optional['logic'] : null; $this->return_properties = isset($optional['returnProperties']) ? $optional['returnProperties'] : null; $this->included_properties = isset($optional['includedProperties']) ? $optional['includedProperties'] : null; $this->diversity = isset($optional['diversity']) ? $optional['diversity'] : null; @@ -238,7 +250,7 @@ public function __construct($user_id, $count, $optional = array()) { $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null; $this->optional = $optional; - $existing_optional = array('filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); + $existing_optional = array('filter','booster','cascadeCreate','scenario','logic','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); foreach ($this->optional as $key => $value) { if (!in_array($key, $existing_optional)) throw new UnknownOptionalParameterException($key); @@ -287,6 +299,8 @@ public function getBodyParameters() { $p['cascadeCreate'] = $this-> optional['cascadeCreate']; if (isset($this->optional['scenario'])) $p['scenario'] = $this-> optional['scenario']; + if (isset($this->optional['logic'])) + $p['logic'] = $this-> optional['logic']; if (isset($this->optional['returnProperties'])) $p['returnProperties'] = $this-> optional['returnProperties']; if (isset($this->optional['includedProperties'])) diff --git a/src/RecommApi/Requests/RecommendUsersToItem.php b/src/RecommApi/Requests/RecommendUsersToItem.php index 4aea392..4bad08d 100644 --- a/src/RecommApi/Requests/RecommendUsersToItem.php +++ b/src/RecommApi/Requests/RecommendUsersToItem.php @@ -40,6 +40,12 @@ class RecommendUsersToItem extends Request { * @var string $scenario Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. */ protected $scenario; + /** + * @var string| $logic Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. + */ + protected $logic; /** * @var bool $return_properties With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. * Example response: @@ -127,6 +133,11 @@ class RecommendUsersToItem extends Request { * - *scenario* * - Type: string * - Description: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. + * - *logic* + * - Type: string| + * - Description: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. * - *returnProperties* * - Type: bool * - Description: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. @@ -195,6 +206,7 @@ public function __construct($item_id, $count, $optional = array()) { $this->booster = isset($optional['booster']) ? $optional['booster'] : null; $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null; $this->scenario = isset($optional['scenario']) ? $optional['scenario'] : null; + $this->logic = isset($optional['logic']) ? $optional['logic'] : null; $this->return_properties = isset($optional['returnProperties']) ? $optional['returnProperties'] : null; $this->included_properties = isset($optional['includedProperties']) ? $optional['includedProperties'] : null; $this->diversity = isset($optional['diversity']) ? $optional['diversity'] : null; @@ -202,7 +214,7 @@ public function __construct($item_id, $count, $optional = array()) { $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null; $this->optional = $optional; - $existing_optional = array('filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','expertSettings','returnAbGroup'); + $existing_optional = array('filter','booster','cascadeCreate','scenario','logic','returnProperties','includedProperties','diversity','expertSettings','returnAbGroup'); foreach ($this->optional as $key => $value) { if (!in_array($key, $existing_optional)) throw new UnknownOptionalParameterException($key); @@ -251,6 +263,8 @@ public function getBodyParameters() { $p['cascadeCreate'] = $this-> optional['cascadeCreate']; if (isset($this->optional['scenario'])) $p['scenario'] = $this-> optional['scenario']; + if (isset($this->optional['logic'])) + $p['logic'] = $this-> optional['logic']; if (isset($this->optional['returnProperties'])) $p['returnProperties'] = $this-> optional['returnProperties']; if (isset($this->optional['includedProperties'])) diff --git a/src/RecommApi/Requests/RecommendUsersToUser.php b/src/RecommApi/Requests/RecommendUsersToUser.php index deebdde..d50c439 100644 --- a/src/RecommApi/Requests/RecommendUsersToUser.php +++ b/src/RecommApi/Requests/RecommendUsersToUser.php @@ -40,6 +40,12 @@ class RecommendUsersToUser extends Request { * @var string $scenario Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. */ protected $scenario; + /** + * @var string| $logic Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. + */ + protected $logic; /** * @var bool $return_properties With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. * Example response: @@ -139,6 +145,11 @@ class RecommendUsersToUser extends Request { * - *scenario* * - Type: string * - Description: Scenario defines a particular application of recommendations. It can be for example "homepage", "cart" or "emailing". You can see each scenario in the UI separately, so you can check how well each application performs. The AI which optimizes models in order to get the best results may optimize different scenarios separately, or even use different models in each of the scenarios. + * - *logic* + * - Type: string| + * - Description: Logic specifies particular behavior of the recommendation models. You can pick tailored logic for your domain (e-commerce, multimedia, fashion ...) and use case. + * See [this section](https://docs.recombee.com/recommendation_logic.html) for list of available logics and other details. + * The difference between `logic` and `scenario` is that `logic` specifies mainly behavior, while `scenario` specifies the place where recommendations are shown to the users. * - *returnProperties* * - Type: bool * - Description: With `returnProperties=true`, property values of the recommended users are returned along with their IDs in a JSON dictionary. The acquired property values can be used for easy displaying the recommended users. @@ -216,6 +227,7 @@ public function __construct($user_id, $count, $optional = array()) { $this->booster = isset($optional['booster']) ? $optional['booster'] : null; $this->cascade_create = isset($optional['cascadeCreate']) ? $optional['cascadeCreate'] : null; $this->scenario = isset($optional['scenario']) ? $optional['scenario'] : null; + $this->logic = isset($optional['logic']) ? $optional['logic'] : null; $this->return_properties = isset($optional['returnProperties']) ? $optional['returnProperties'] : null; $this->included_properties = isset($optional['includedProperties']) ? $optional['includedProperties'] : null; $this->diversity = isset($optional['diversity']) ? $optional['diversity'] : null; @@ -226,7 +238,7 @@ public function __construct($user_id, $count, $optional = array()) { $this->return_ab_group = isset($optional['returnAbGroup']) ? $optional['returnAbGroup'] : null; $this->optional = $optional; - $existing_optional = array('filter','booster','cascadeCreate','scenario','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); + $existing_optional = array('filter','booster','cascadeCreate','scenario','logic','returnProperties','includedProperties','diversity','minRelevance','rotationRate','rotationTime','expertSettings','returnAbGroup'); foreach ($this->optional as $key => $value) { if (!in_array($key, $existing_optional)) throw new UnknownOptionalParameterException($key); @@ -275,6 +287,8 @@ public function getBodyParameters() { $p['cascadeCreate'] = $this-> optional['cascadeCreate']; if (isset($this->optional['scenario'])) $p['scenario'] = $this-> optional['scenario']; + if (isset($this->optional['logic'])) + $p['logic'] = $this-> optional['logic']; if (isset($this->optional['returnProperties'])) $p['returnProperties'] = $this-> optional['returnProperties']; if (isset($this->optional['includedProperties']))