| パラメータ名 | 内容 |
|---|---|
| search_key{cid} | 検索キー |
| search_operator{cid} | “検索オペレータ（式）、下記の値を指定可能 eq（=）, ne（!=）, ge（>=）, gt（>）, le（<=）, lt（<）, like” |
| search_value{cid} | 検索値 Nullを指定する場合は、何も指定しません。 例： search_value1= |
search_key{cid}、search_operator{cid}、search_value{cid}の3つで1つの検索条件を表します。 {cid}は、関連する条件で同一である必要があります。
例1)「Name1=山田 and Name2=太郎」を表す検索条件
※日本語・記号は、文字コードUTF-8でURLエンコードする必要があります。
https://sample.smartseminar.jp/services/rest/visitor?api_key=55b985f4994bf940b63f6bfb0aec3f70&search_key1=Name1&search_operator1=eq&search_value1=%e5%b1%b1%e7%94%b0&search_key2=Name2&search_operator2=eq&search_value2=%e5%a4%aa%e9%83%8e&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_sig=b4a7f220f77d9319330e1f81ce2c6f8e7759790d
| 項目 | 値 |
|---|---|
| api_key | 55b985f4994bf940b63f6bfb0aec3f70 |
| token | xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx |
| search_key1 | Name1 |
| search_operator1 | eq |
| search_value1 | 山田 |
| search_key2 | Name2 |
| search_operator2 | eq |
| search_value2 | 太郎 |
シグネチャ計算の種は、上記パラメータを各（項目+値）の文字列の昇順で並べ替えます。
api_key55b985f4994bf940b63f6bfb0aec3f70search_key1Name1search_key2Name2search_operator1eqsearch_operator2eqsearch_value1山田search_value2太郎tokenxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
※ (注意)
api_key・・・search_key1Name1search_operator1eqsearch_value1山田search_key2Name2search_operator2eqsearch_value2太郎・・・
とはなりませんので注意してください。
上記、シグネチャ計算の種をHMAC-SHA-1 ハッシュ値を計算しapi_sigを作成します。
※ シグネチャ(api_sig)の作成詳細は、シグネチャ(api_sig)の仕様をご覧ください。
例2)「2009年11月16日以降」を表す検索条件
※日付型は、タイムゾーンまで指定する必要があります。記号（「:」「+」）は文字コードUTF-8でURLエンコードする必要があります。
https://sample.smartseminar.jp/services/rest/visitor?api_key=55b985f4994bf940b63f6bfb0aec3f70&search_key1=DateRegist&search_operator1=ge&search_value1=2009-11-16T00%3A00%3A00%2B09&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99
|項目|値| |:—:|:—:| |api_key|55b985f4994bf940b63f6bfb0aec3f70| |token|xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx| |search_key1|DateRegist| |search_operator1|ge| |search_value1|2009-11-16T00:00:00+09|
シグネチャ計算の種は、上記パラメータを各（項目+値）の文字列の昇順で並べ替えます。
api_key55b985f4994bf940b63f6bfb0aec3f70search_key1DateRegistsearch_operator1gesearch_value12009-11-16T00:00:00+09tokenxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
上記、シグネチャ計算の種をHMAC-SHA-1 ハッシュ値を計算しapi_sigを作成します。
※ シグネチャ(api_sig)の作成詳細は、シグネチャ(api_sig)の仕様をご覧ください。
検索条件パラメータを下記のように指定することで、AND条件またはOR条件となります。
・AND条件：{cid}の異なる検索条件はAND条件になります。 例）「Name1=池田 and CompanyName=○×商事」を表す検索条件
https://sample.smartseminar.jp/services/rest/visitor?search_key1=Name1&search_operator1=eq&search_value1=%e6%b1%a0%e7%94%b0&search_key2=CompanyName&search_operator2=eq&search_value2=%e2%97%8b%c3%97%e5%95%86%e4%ba%8b&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99
・OR条件：{cid}の同じSearchValueを複数並べるとOR条件になります。 例）「Id=1 or Id=2 or Id=3」を表す検索条件
https://sample.smartseminar.jp/services/rest/visitor?search_key1=Id&search_operator1=eq&search_value1=1&search_value1=2&search_value1=3&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99
検索オペレータに「like」を渡して検索を行なった場合、検索結果は常に部分一致で取得されるため、前方一致および後方一致での検索はできません。
本ドキュメントで定義していない検索条件キーを指定した場合、正しい検索結果を返却しない場合があります。
| パラメータ名 | 内容 |
|---|---|
| order | 並び順の項目 並び順の対象となる項目を指定します 例：リードIDで並び替える場合 order=VisitorId |
| direction | 並び順を指定します。 「asc」（昇順：デフォルト）または「desc」（降順） |
orderで並び順の項目、directionで並び順を指定します。 昇順（asc）で並び替える場合は、デフォルトのため指定不要です。
例1)IDで降順（desc）に並び替える場合
https://sample.smartseminar.jp/services/rest/visitor?direction=desc&order=Id&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99=bcfe66c4a8ac9de324c66487a7c125ea772e29bd&api_key=55b985f4994bf940b63f6bfb0aec3f70
下記のような並び順指定はサポートしていません。
| パラメータ名 | 内容 |
|---|---|
| limit | 1回のリクエストで取得するレコード件数を指定します。 （最大1000件） |
| offset | レコードのオフセットを指定します |
limitで1回に取得するレコードの件数、offsetで取得するデータの開始位置を指定します。
例1）10件のデータを30件目から取得する場合
https://sample.smartseminar.jp/services/rest/visitor?order=Id&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99&limit=10&&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_key=55b985f4994bf940b63f6bfb0aec3f70&offset=30
1回のリクエストで取得可能なデータ件数が1000件のため、1000件以上のデータを取得する場合は、offsetを使用して取得する必要があります。 offset=1000を指定することにより、1001件目から1000件（1001～2000番目の値）を取得できます。
例：2500件のデータを取得する場合は、「limit=1000&offset=0」、「limit=1000&offset=1000」、「limit=1000&offset=2000」の3回のリクエストが必要です。
★ limitの件数は、Id等の値ではなく、インデックスでカウントされます。 例1：Id=1,3,5,7,9,11,13,15のデータが存在する場合、limit=3を指定すると、Id=1,3,5のデータが取得されます。 例2：Id=1,3,5,7,9,11,13,15のデータが存在する場合、limit=3、offset=3を指定すると、Id=7,9,11のデータが取得されます。
取得対象のデータが随時更新されるような場合、offsetではなく条件を変更して取得し直すことを検討してください。 データ取得中に対象のデータが更新されると、取得対象のリストが増減したり並び順が変わることでoffsetの位置がずれることがあります。 条件を変更して取得し直すには、並び順をIdなどの一意かつ不変なものとして、その値で絞り込んでください。
例えば、ある一定の更新日時の期間のデータを取得して、更新する場合は、Idと更新日時を検索条件に指定し、並び順にIdを指定してください。
※ 2022年3月29日00:00:00から2022年3月30日00:00:00までに更新されたリードを100件ずつ取得する場合
マーケティングプラットフォームのAPIはRESTfulなAPIとして設計されているため、あるリソース（例えばリードなど）を検索する場合にはGETメソッドを使用します。 しかしながら、GETメソッドで複雑な検索を行うとURLが非常に長くなってしまい、正しくAPIが実行されないケースがあります。 例えば2010年現在、InternetExplorerというブラウザはURLに使用できる最大文字数を2083バイトまでに制限していますし、代表的なWebサーバのApacheはリクエスト行の長さを8190バイト(うち、URL部分は8177バイト)までと制限しています。
複雑な検索を実行した結果、非常に長いURLになってしまうケースを想定し、マーケティングプラットフォームAPIではリクエストボディによる検索条件指定もサポートしています。
APIキー、認証トークン、およびシグネチャについては、下記の例のようにURLパラメータとして指定します。 この場合シグネチャはAPIキーと認証トークンを種として計算します。
https://sample.smartseminar.jp/services/rest/visitor?api_key=xxxxx&token=xxxxxx&api_sig=xxxxx
検索条件は下記のようにXMLフォーマットで定義し、リクエストボディにセットします。
リクエストボディXMLサンプル
<?xml version='1.0' encoding='UTF-8'?>
<Request xmlns="http://smartseminar.jp/" version='1.6'>
<SearchKey1>Id</SearchKey1>
<SearchOperator1>eq</SearchOperator1>
<SearchValue1>1</SearchValue1>
<SearchValue1>2</SearchValue1>
<SearchValue1>3</SearchValue1>
<SearchValue1>4</SearchValue1>
<SearchValue1>5</SearchValue1>
<SearchValue1>6</SearchValue1>
<SearchValue1>7</SearchValue1>
<SearchValue1>8</SearchValue1>
<SearchValue1>9</SearchValue1>
<order>Id</order>
<direction>desc</direction>
<limit>1000</limit>
<offset>2000</offset>
</Request>
通常GETメソッドはリクエストボディを使用できませんので、POSTメソッドを使用します。 リクエストヘッダの”X-HTTP-Method-Override”に”GET”を指定した上で、上記リクエストボディをPOSTします。
尚、リクエストボディで検索を実行する場合、APIキーと認証トークンの2つのパラメータだけでシグネチャ計算をすることになります。 セキュリティ強度に不安が残る場合、任意のパラメータを追加して強度を増すことも出来ます。「認証トークン」節の「シグネチャ計算にパラメータを加えることによるセキュリティ強化」の項をご参照ください。
マーケティングプラットフォームは、システムに予め用意されている基本項目のほかに、追加項目というユーザ定義型の項目を使用することができます。追加項目はユーザが定義できるため、システム毎に、追加項目の数、データ型が異なります。
追加項目のデータ型は、フォーム種別に対応します。
| フォーム型 | データ型 | XMLサンプル |
|---|---|---|
| テキスト | string | <Attribute1>テキスト</Attribute1> |
| テキストエリア | string | <Attribute2>テキストエリアに記載された文章です。</Attribute2> |
| ラジオボタン | Attribute{aid}List | <Attribute3List> <Attribute3> <Attribute3Id>1</Attribute3Id> <Attribute3Name>選択肢１ </Attribute3Name> </Attribute3> </Attribute3List> |
| チェックボックス | Attribute{aid}List | <Attribute4List> <Attribute4> <Attribute4Id>1</Attribute4Id> <Attribute4Name>選択肢１ </Attribute4Name> </Attribute4> <Attribute4> <Attribute4Id>2</Attribute4Id> <Attribute4Name>選択肢２ </Attribute4Name> </Attribute4> </Attribute4List> |
| プルダウンメニュー | Attribute{aid}List | <Attribute5List> <Attribute5> <Attribute5Id>1</Attribute5Id> <Attribute5Name>選択肢１ </Attribute5Name> </Attribute5> </Attribute5List> |
| 画像 | Attribute{aid}File | <Attribute6File> <Attribute6FileExtension>jpg</Attribute6FileExtension> <Attribute6FileId>6</Attribute6FileId> <Attribute6FileName>画像名</Attribute6FileName> <Attribute6FilePath>/public/file/download? id=6&view=1</Attribute6FilePath> </Attribute6File> <Attribute6SlaveAlt>表示用代替テキスト</Attribute6SlaveAlt> ※リード（VisitorDataType）やアンケート（EnqueteType）の追加項目において、代替テキストの使用はできません。 |
| ファイル | Attribute{aid}File | <Attribute7File> <Attribute7FileExtension>txt</Attribute7FileExtension> <Attribute7FileId>7</Attribute7FileId> <Attribute7FileName>ファイル名</Attribute7FileName> <Attribute7FilePath>/public/file/download? id=7&view=1</Attribute7FilePath> </Attribute7File> |
| 数値 | DoubleType | <Attribute8>12345</Attribute8> |
| 日付 | date | <Attribute9>2017-01-01</Attribute9> |
| 日時 | dateTime | <Attribute10>2017-01-01T01:01:01</Attribute10> |
各型の追加項目を検索条件に使用する場合は、指定可能なオペレーターは以下の表のとおり
| eq(=) | ne(!=) | gt(>) | lt(<) | ge(>=) | le(<=) | like | |
|---|---|---|---|---|---|---|---|
| テキスト | ○ | ○ | × | × | × | × | ○ |
| テキストエリア | ○ | ○ | × | × | × | × | ○ |
| ラジオボタン | ○ | ○ | × | × | × | × | × |
| チェックボックス | ○ | ○ | × | × | × | × | × |
| プルダウンメニュー | ○ | ○ | × | × | × | × | × |
| 画像 | ○※ | ○※ | × | × | × | × | × |
| ファイル | ○※ | ○※ | × | × | × | × | × |
| 数値 | ○ | ○ | ○ | ○ | ○ | ○ | × |
| 日付 | ○ | ○ | ○ | ○ | ○ | ○ | × |
| 日時 | ○ | ○ | ○ | ○ | ○ | ○ | × |
※ 検索値が空白値の場合は検索できません。
選択型項目であるAttributeList（チェックボックス、プルダウン、ラジオボタン）を検索条件に利用する場合には、 <Attribute{aid}List> の <Attribute{aid}id> カラムの値を指定してください。
Attribute{aid}で検索する場合、下記表に従って検索条件を指定してください。
検索条件に指定できる検索項目値はAttribute{aid}Idのみで、Attribute{aid}Nameは指定できません。
| 項目 | 値 |
|---|---|
| 検索項目(search_keyN) | Attribute{aid} |
| 検索演算子(search_operatorN) | eq,ne,lt,gt,le,ge |
| 検索項目値(search_valueN) | Attribute{aid}Idの値 |
また、ファイル型項目であるAttribute{aid}File（ファイル、画像）を検索条件に利用する場合には、 <Attribute{aid}File> の <Attribute{aid}FileId> カラムの値を指定してください。
Attribute{aid}で検索する場合、下記表に従って検索条件を指定してください。
検索条件に指定できる検索項目値は、Attribute{aid}FileId のみで、Attribute{aid}FileExtensionやAttribute{aid}FileName,Attribute{aid}FilePath は指定できません。
| 項目 | 値 |
|---|---|
| 検索項目(search_keyN) | Attribute{aid} |
| 検索演算子(search_operatorN) | eq,ne,lt,gt,le,ge |
| 検索項目値(search_valueN) | Attribute{aid}FileIdの値 |
選択型項目・ファイル型項目を検索条件に使用する際のサンプル
https://sample.smartseminar.jp/services/rest/visitor?search_key1=Attribute5&search_operator1=eq&search_value1=1&api_sig=44c477c44e599f6f4f303b4d41a002b03acb9b99&token=xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx&api_key=55b985f4994bf940b63f6bfb0aec3f70
選択型項目（ラジオボタン、チェックボックス、プルダウンメニュー）を未選択で指定する方法は、値に何も指定せず、<Attribute{cid}Id> や <Attribute{cid}Name> またはその両方を送信します。
（下記サンプル参照） なお、<Attribute{cid}Id>と<Attribute{cid}Name>を両方送信する場合に、片方に有効な値が設定されている場合は、もう片方に値の指定がなくても未選択することは出来ません。 また、無効なNameの値のみを指定した場合は、未選択の指定がされます。 （無効なIdを設定した場合は、エラーが返ります。）
選択型項目における未選択指定のサンプル
<Attribute4List>
<Attribute4>
<Attribute4Id></Attribute4Id>
</Attribute4>
</Attribute4List>
マーケティングプラットフォームでは数値型項目のデータを浮動小数点数として扱います。 数値型の値の範囲は-1,000,000,000,000,000 < 値 < 1,000,000,000,000,000、アンダーフローの閾値は1e-307, -1e-307です。 有効桁数は15桁で、整数部、小数部合わせて16桁以上の数値が入力された場合16桁目が四捨五入されます。また、小数部末尾に0が続く場合はこれを無視します。
例1： 1.234567890123456 が入力された場合、16桁目が四捨五入され 1.23456789012346 が入力値になります。 例2： 1.2300000 が入力された場合、小数部末尾の0を無視し 1.23 が入力値になります。
指数表現は使用可能ですが、Nan（非数）やInfinity（無限大）は使用できません。 入力が指数表現の場合、マーケティングプラットフォーム内では指数表現を解いたものを扱います。また、絶対値が0,0001未満の入力は入力時の表現にかかわらず指数表記になります。
例3： 1e5 が入力された場合、 管理画面での表示やAPIで取得したときは100000 が入力値になります。 例4： 0.00001 が入力された場合、 管理画面での表示やAPIで取得したときは1e-05 が入力値になります。
日付型の値のフォーマットはYYYY-mm-ddです。 日付型の値の範囲は1902-01-01 <= 値 <= 2037-12-31です。
日時型の値のフォーマットはYYYY-mm-ddTHH:MM:SSです。 ※検索値の後ろにタイムゾーンもサポートします。 例1： 2017-01-01T11:11:11+09:00 例2： 2017-01-01T11:11:11Z(ZがUTC+00:00です。) 例3： 2017-01-01T11:11:11 日時型の値の範囲は1902-01-01T00:00:00Z <= 値 <= 2037-12-31T23:59:59Zです。