Skip to content

Environment setup

Environment setup

Overview

To prepare GAIP for your site, there are 2 main steps

  1. Mapping creation
  2. Index creation

For this, we will use the API endpoints of GAIP that are listed here

You can also access here from the Solutions page > Projects > Project details (Click on your project name) > Settings > Sandbox.

Find the details of each step below.


1. MAPPING CREATION

Recommender engine has some default Keys which are required to run the solution. You have to map the data source keys (of your website) with recommender keys for integrating your product.

For this we will use the APIs listed under Item Mapper in the sandbox. When you expand POST/v1/mapper, you will see the list of the parameters (Both mandetory and optional) and an example value.

You can simply replace the values in the example with your item catalogue keys and hit Execute to finish the mapping of your product catalogue Keys with GAIP keys.

Note that there are some mandatory and some optional items, please ensure to pass all the mandatory items.

After execution, confirm the server response is success.

Example of this item mapper creation

Here, we will use doozie shop as an example E-commerce site. We can see the catalogue information of this site using the Shop API and will use this as example data source. doozie shop searches multiple E-commerce inventory and finds the most suitable items.

Request endpoint to fetch data from Shop API:

POST https://api.doozie.shop/v1/sandbox#/

In items/search, put below request body

{
  "rakuten_query_parameters": {
    "keyword": "shirt"
  },
  "yahoo_query_parameters": {
    "query": "string --> This is the only required parameter"
  },
  "from_scheduler": false
  } 

This request body will search the item catalogue with the keyword "shirt"

The example response should look like below:

  {
    "success": true,
    "result": [
      {
        "item_id": "ra_hworks:10000926",
        "title": "【選べる5枚で最大30%OFFクーポン】 ワイシャツ 長袖 3190円→2360円 形態安定 メンズ 楽天ランキンク 受賞 ドレスシャツ Yシャツ 標準体 細身体 スリム おしゃれ シャツ イージーケア カッターシャツ セット 仕事 ビジネス 結婚式  ブルー ボタンダウン 30代 40代",
        "description": "こだわりデザイン・ドレスシャツ/ワイシャツ旬を表現するシャツのおしゃれな着こなし。さり気なくお洒落感を効かせてくれる、当店の人気商品です。生産工場と提携し、企画から納品までの無駄を削減し、絶妙にシャープでエッジの効いたスタイルを提供できます。スタイリッシュさをアピールする工夫が満載ながら、スーツスタイルもノータイスタイルをあくまでも上品に格上げしてくれる。「仕事がデキる」「取引先や上司にウケる」「女性にモテる」ビジネスシーンやドレスシーンでのキレイめスタイルに是非取り入れてみてはいかがですか?ご注文方法(1)ご希望のワイシャツのうち1枚を選択し、「商品をかごに追加」ボタンを押す(2)同様に、2枚目を選択し「商品をかごに追加」ボタンを押す(3)ご希望の枚数になるまで、上記を繰り返す(4)最後に「ご購入手続きへ」ボタンを押し、商品の内容や枚数にお間違いがいないかご確認ください※商品を選択し直す場合は、ブラウザの戻るボタン(< など)を押して商品選択画面に戻り、(1)〜(3)の手順を繰り返してください。型番SHIRT-Z0x SHIRT-ZW00x SHIRT-100x SHIRT-200x SHDZ20 SWSM31-(個別の商品コードはラインナップ画像を参照) SHDZ15-商品情報・ポケット数:1・カフスボタン対応・コンバーチブルカフス・袖口のサイズが調整できるアジャスターボタン・丈夫で速乾性のある綿混素材・形態安定素材・衿やカフスのシワやタルミを防ぐトップヒューズ加工・スペアボタン・背タック・レギュラーカラー・ワイドカラー・セミワイドカラー・ボタンダウン・カッタウェイサイズ・素材・カラーサイズ:スリムS・スリムM・スリムL・S・M・L・LL・3L・4L・5L首周り:37・39・41・43・45・47・49裄丈:80・82・84・86・88綿25% ポリエステル75%(イージーケア性の高い生地)2生地使い仕様こだわりボタン白(ホワイト)・青(ブルー)・水色(サックス)・桃色(ピンク・ライトピンク)ストライプ・ブロック・ドビードット・ドット・織柄・ ドビー・ツイル・市松チェック付属品-メーカー希望小売価格はメーカーカタログに基づいて掲載しています店用管理番号gp2gp1wc1cb1sc1sc2sk1tn1tn2cf1nk1nk2nk3nk4nk5nk6nk7bs1bs2bg1be1be2mb1mb2sn1sn2sn3sn4sn5sn6sn7sn8sn9si1si2si4si5si6si7si8si9sr1sk3sk2hs1ld1ld2ys1ck1kh1ss1nk8nk9na1nka1ks1この商品のお問い合わせ番号SBR-shirt-b0080スマートビズはビジネスアパレル専門店です。おしゃれなデザイン性はもちろん、働くビジネスパーソンのために機能性も重視しています。皆様のライフスタイルに沿ったご提案を心がけ、迅速丁寧なお客様サポートを行ってまいります。またスマートビズはワイシャツ(ドレスシャツ・Yシャツ・カッターシャツ)を中心に販売しております。最近ではビジネスカジュアル(オフィスカジュアル・ビジカジ)がビジネスシーンでも浸透してきており、デザイン性に優れたワイシャツを着る人が増えています。また、お手入れを楽にすべく、アイロンの手間が省ける、イージーケアの商品を取り扱っております。スマートビズでは、標準体はもちろん、ゆったりとした大きめのサイズからスリム(justスタイルや細身体)まで、幅広いサイズのワイシャツを取り扱っています。選ばれているワード着用層[着用層]10代 20代 30代 40代 50代 60代 70代 メンズ 男子 男性 紳士 営業 外回り 父親着用シーン仕事 通勤 会議 打ち合わせ 商談 ビジネス リモートワーク テレワーク 在宅勤務 在宅ワーク デジカジ ノータイ ノージャケット ジャケパン スーツ セットアップ     オールシーズン 1月 2月 3月 4月 5月 6月 7月 8月 9月 10月 11月 12月楽天市場デイリーランキングワイシャツ部門(2017年11月14日)No.1獲得LINEUP-ラインナップ一覧-各商品の詳細はページ下部をご確認ください。-メンズファッションランキング1位(2022年3月14日)Tシャツやボトムスなど幅広い商品が並ぶ楽天市場メンズファッション部門全商品の中からこちらのワイシャツが1位を獲得しました!ワイシャツ販売開始以来(2012年〜)132万人のご愛好者様突破!実店舗にないお洒落なデザイン楽天年間ランキング3年連続獲得!※2017年/2018年/2019年度上半期さらに!日本全国のお客様に選ばれ続けてレビュー高評価4.26(2020年4月28日現在)たくさんの嬉しい声が届きました。ありがとうございます。いい買い物ができて満足これまで1500円以下のワイシャツは購入したことがなかったので、正直、品質に不安がありました。注文後翌日にすぐ届くスピード感も逆に不安でしたが、手にとってびっくり!!まだ洗濯していないので、形状記憶の程度はわかりませんが、さっぱりした着心地です。いい買い物ができたと満足です。安いだけじゃない!Yシャツは着るたびに丁寧にクリーニングしても襟元の汚れは取れにくく着れなくなってきます。高価なYシャツでも同様です。今までは高価なものをより長くと考えていましたが、リーズナブルなもので気に入ったものを取り換えながら…と考えを切り替えました。リーズナブルな価格にもかかわらず、高価なものに匹敵する着用感でなんの問題もありません。今後も、利用していきたいと考えています。ワイシャツ販売数「世界一」に挑戦!!選ばれる3つの理由仕事が加速するお洒落なデザイン生活を向上させるイージーケア素材1枚でも送料無料まとめるとクーポン割引最短当日出荷!細部のデザインへのこだわり仕事が加速するお洒落なデザイン毎日着るシャツだからこそ、かっこよくありたい。主張しすぎず、遊びを効かせたデザインで、仕事をさらに加速させることごできます。こだわりの縫製で頑丈にしっかりとした生地は良質な糸から厚みにある生地は、良質な糸から作られます。高級糸”コーマ糸”を使用した品質の高い生地を使用。インターロック縫製で各パーツ丈夫に、頑丈に。高級綿糸コーマ糸綿花を紡ぐ最終工程で繊維の短い部分を除き毛羽立ちを抑えた高級綿糸のことです。毛羽立ちが少なく肌触りの良い生地に。立体製図・立体裁断CAD(コンピュータでの製図)で立体製図・立体裁断を行っています。身体は丸みを帯びているのでより丸みに沿った生地を裁断できます。幾度も行う検品ワイシャツを作る工程で機械だけに頼ることなく手作業で作っています。検品はシャツ1枚につき7回行われ、品質管理を徹底しております。生地になる糸からこだわりました。よりよい商品を皆様にお届けするために。信頼できる提携工場で生地が作られる工程から最終仕上げまで、機械に頼ることなく人の手によって作り上げられます。中間マージンがない当店はコストを抑えられる!究極のコストダウン品質への徹底的なこだわり工場と直接提携することによりコスト削減を実現しました。また、工場と直接やり取りすることで、品質にも縫製にも積極的にこだわりました。スタッフが着てみました(身長:173cm/体重:69kg)ノーマルタイプだと袖周りのダボつきが少し気になりました。ダボつきをスッキリ見せたい人はスリムタイプがおすすめです。反対にゆったり着たい人はノーマルタイプでも◎胸周りがすこしごついため、Sだとピッタリしすぎていて少し窮屈。そのため普段Mサイズの僕はスリムタイプのMがピッタリでした。スリムS着用(身長:165cm/体重:58kg)スリムS着用(身長:172cm/体重:52kg)スリムM着用(身長:173cm/体重:62kg)ノーマルL着用(身長:178cm/体重:75kg)",
        "headline": "ワイシャツ 長袖 スリム Yシャツ 形態安定 ドレスシャツ ノーネクタイ おしゃれ デザイン メンズ 結婚式 ビジネス 仕事 白シャツ ブルー  ボタンダウン ワイド 標準体 襟高 セット",
        "availability": true,
        "affiliate_rate": 4,
        "price": 2360,
        "currency": "JPY",
        "shop_id": "hworks",
        "shop_name": "スマートビズ-ワイシャツ専門店-",
        "review_count": 2836,
        "review_average": 4.26,
        "genre_id": "206363",
        "brand": null,
        "shop_url": "https://hb.afl.rakuten.co.jp/hgc/g00rgm95.h3cpt446.g00rgm95.h3cpu696/?pc=https%3A%2F%2Fwww.rakuten.co.jp%2Fhworks%2F&m=http%3A%2F%2Fm.rakuten.co.jp%2Fhworks%2F",
        "item_url": "https://hb.afl.rakuten.co.jp/hgc/g00rgm95.h3cpt446.g00rgm95.h3cpu696/?pc=https%3A%2F%2Fitem.rakuten.co.jp%2Fhworks%2Fshirt-b0080%2F&m=http%3A%2F%2Fm.rakuten.co.jp%2Fhworks%2Fi%2F10000926%2F",
        "image_urls": [
          "https://thumbnail.image.rakuten.co.jp/@0_mall/hworks/cabinet/001/014/shirt-b0080.jpg",
          "https://thumbnail.image.rakuten.co.jp/@0_mall/hworks/cabinet/001/014/b0080-lineup.jpg",
          "https://thumbnail.image.rakuten.co.jp/@0_mall/hworks/cabinet/banner/coupon202308-shdz_sq.jpg"
        ],
        "tag_ids": [
          1000903,
          1008869,
          1039853,
          1013746,
          1037371,
          1019464,
          1000568,
          1000567,
          1000566,
          1000565,
          1000564,
          1003785,
          1000873,
          1000428,
          1000426,
          1000424,
          1000422,
          1000420
        ],
        "tags": [],
        "shipping_overseas": "",
        "condition": 1,
        "genre_name": null,
        "parent_genre_categories": null,
        "shop_review_count": null,
        "shop_review_average": null,
        "tax_included": true,
        "point_multiplier": 1,
        "best_seller": false,
        "sale_start_time": "",
        "sale_end_time": "",
        "platform": "rakuten"
      },
      ...................................
    ],
    "job_id": "save_tags_and_genres_1692242904.6633978"
  }

This shows the keys that doozie shop has for its products. Now we can create a mapping with GAIP keys, and use the POST /v1/mapper endpoint of GAIP. In this endpoint, we will pass the keys of above data source.

Here is an example of a mapper that we built for our Shop API, based on the keys from Dozzie shop above:

{
  "key_map": {
    "item_id": "item_id",
    "title": "title",
    "second_title": "headline",
    "third_title": "shop_name",
    "fourth_title": "genre_name",
    "availability": "availability",
    "description": "description",
    "image_url": "image_urls",
    "image_url_type": "LIST_STR",
    "item_url": "item_url",
    "price": "price",
    "categories": [
      {
        "name": "genre_id",
        "separator": ""
      },
    ],
    "custom":[],
    "flag": [
      "condition"
    ]
  }
}

Sample Example

You can find sample code for this implementation here


You can update any of mapped keys with PUT /v1/mapper endpoint and check the mapper you build from GET /v1/mapper endpoint.

Behavior mapping key

Similar to the item mapping key, there are some default keys for user behavior data.

This step is required If you want to save user behavior data through CSV files.

We have discussed about this more in the Data integration and user behavior integration section

To immplement this, please follow similar steps as above.

The required parameters and example body can be found here.

However in this case please note that there are four sets of endpoints for Browsing history, purchase history, rating history, user detail. You have to create mapper for each if you want to import the data.

2. Index creation

In this step, you need to create indices. We need multiple indices to run recommender solution successfully. These indices will create the necessary schemas to hold your data.

There are 3 endpoints here

  1. POST /v1/index/create --> Create indices to hold your data

  2. DELETE /v1/index/delete --> Delete incides

  3. POST /v1/reindex --> Creates index with new mappings and settings and create alias for new index

Create Index

Request endpoint

POST /v1/index/create
Simply use your project key and API and click execute to create the indeces for your project. Note that this will throw an error if the mapping in the previous step is not done correctly.

After the successful execution all the necessary index will be created and item index will be created in the background. You can check the status of item index creation with a task id from GET /v1/tasks/{task_id} API at the bottom of the page.

Please confirm the task was success.

Delete Index

You can delete an existing index with this endpoint.

Request endpoint

DELETE /v1/index/delete 
Available values are items, image_features, browse, purchase, ratings, search, stats, settings, user, tasks, logs.

If you Delete any index, please ensure to create the index again, unless you will get error when trying to input data/item catalogue or run training.

Reindex

In Elastic search, reindexing is the process of copying data from one index to another, either within the same cluster or to a different cluster. This can be useful in a variety of situations, such as:

  • Updating the mapping of an index: If you need to make changes to the mapping of an index, you can create a new index with the updated mapping and then reindex the data from the old index to the new one.

  • Moving data from one index to another: If you need to move data from one index to another, you can reindex the data from the source index to the destination index.

  • Updating the data with new data: If you have updated data that you want to add to an index, you can reindex the data with the updated data.

  • Changing the shard count of an index: If you need to change the number of shards that an index is using, you can reindex the data to a new index with the desired number of shards.

We can use Reindex API to copy data from index to another index.

Request Endpoint:

POST /v1/reindex

Here is an example how to pass mappings and settings in request body:

{
  "index_type": "items",
  "mappings": {
    "settings": {
                "analysis": {
                    "char_filter": {
                        "normalize": {
                            "type": "icu_normalizer",
                            "name": "nfkc",
                            "mode": "compose"
                        }
                    },
                    "tokenizer": {
                        "ja_kuromoji_tokenizer": {
                            "mode": "search",
                            "type": "kuromoji_tokenizer",
                            "discard_compound_token": "true",
                            "user_dictionary_rules": []
                        },
                        "ja_ngram_tokenizer": {
                            "type": "ngram",
                            "min_gram": 2,
                            "max_gram": 3,
                            "token_chars": ["letter", "digit"]
                        }
                    },
                    "filter": {
                        "ja_index_synonym": {
                            "type": "synonym",
                            "lenient": "false",
                            "synonyms": []
                        }

                    },
                    "analyzer": {
                        "ja_kuromoji_index_analyzer": {
                            "type": "custom",
                            "char_filter": ["normalize"],
                            "tokenizer": "ja_kuromoji_tokenizer",
                            "filter": [
                                "kuromoji_baseform",
                                "kuromoji_part_of_speech",
                                "ja_index_synonym",
                                "cjk_width",
                                "ja_stop",
                                "kuromoji_stemmer",
                                "lowercase"
                            ]
                        },
                        "ja_kuromoji_search_analyzer": {
                            "type": "custom",
                            "char_filter": ["normalize"],
                            "tokenizer": "ja_kuromoji_tokenizer",
                            "filter": [
                                "kuromoji_baseform",
                                "kuromoji_part_of_speech",
                                "cjk_width",
                                "ja_stop",
                                "kuromoji_stemmer",
                                "lowercase"
                            ]
                        },
                        "ja_ngram_index_analyzer": {
                            "type": "custom",
                            "char_filter": ["normalize"],
                            "tokenizer": "ja_ngram_tokenizer",
                            "filter": ["lowercase"]
                        },
                        "ja_ngram_search_analyzer": {
                            "type": "custom",
                            "char_filter": ["normalize"],
                            "tokenizer": "ja_ngram_tokenizer",
                            "filter": ["lowercase"]
                        }
                    }
                }
            },
            "mappings": {
                "properties": {
                    "item": {
                        "properties": {
                            "{title}": {
                                "type": "text",
                                "search_analyzer": "ja_kuromoji_search_analyzer",
                                "analyzer": "ja_kuromoji_index_analyzer",
                                "fields": {
                                    "ngram": {
                                        "type": "text",
                                        "search_analyzer": "ja_ngram_search_analyzer",
                                        "analyzer": "ja_ngram_index_analyzer"
                                    }
                                }
                            },
                            "{second_title}": {
                                "type": "text",
                                "search_analyzer": "ja_kuromoji_search_analyzer",
                                "analyzer": "ja_kuromoji_index_analyzer",
                                "fields": {
                                    "ngram": {
                                        "type": "text",
                                        "search_analyzer": "ja_ngram_search_analyzer",
                                        "analyzer": "ja_ngram_index_analyzer"
                                    }
                                }
                            },
                            "{third_title}": {
                                "type": "text",
                                "search_analyzer": "ja_kuromoji_search_analyzer",
                                "analyzer": "ja_kuromoji_index_analyzer",
                                "fields": {
                                    "ngram": {
                                        "type": "text",
                                        "search_analyzer": "ja_ngram_search_analyzer",
                                        "analyzer": "ja_ngram_index_analyzer"
                                    }
                                }
                            },
                            "{description}": {
                                "type": "text",
                                "search_analyzer": "ja_kuromoji_search_analyzer",
                                "analyzer": "ja_kuromoji_index_analyzer",
                                "fields": {
                                    "ngram": {
                                        "type": "text",
                                        "search_analyzer": "ja_ngram_search_analyzer",
                                        "analyzer": "ja_ngram_index_analyzer"
                                    }
                                }
                            },
                            "{price}": {"type": "float"},
                            "{availability}": {"type": "boolean"}
                        }
                    }
                }
            }
    }
}
Available values are items, image_features, browse, purchase, ratings, search, stats, settings, user, tasks, logs. When you define the mappings object, you should use the same keys as in the item mapper that you have built with POST /v1/mapper API.

You might not need analyzers or tokenizers for all indices. You can keep the settings field empty if it is not required. Here is an example,

{
  "index_type": "search",
  "mappings": {
    "settings": {},
    "mappings": {
      "properties": {
        "date": {"type": "date"}
      }
    }
  }
}