ルールAPI

Oracle Data CloudのカテゴリおよびルールのWebサービスを実装して、自分のサイトから収集されたページ属性とユーザー属性を個別に分類したり、自分のオンボーディングされたオフライン・データを分類することができます。分類は、Oracle Data Cloudプラットフォームに転送されたデータが収集されて、プライベート・タクソノミのカテゴリにマッピングされるプロセスです。カテゴリAPIとルール・チェーンAPIを実装すると、階層化されたカテゴリをタクソノミ内に作成して、属性(およびユーザー)が各カテゴリに追加されるタイミングを定義するルールを作成できます。

ルールAPIを使用すると、URLおよびキーと値のペア(phint)に基づく分類ルールを作成して、自分のサイトから抽出されたユーザー・データを、作成したカテゴリにマッピングできます。

ノート: ユーザーがOracle Data CloudプラットフォームUIでキャンペーンを作成することはなくなりました。キャンペーン・ワークフローは、オーディエンス・ワークフローの一部になりました。ただし、プラットフォームでは引き続きキャンペーンを使用して、オーディエンス・データ配信を管理できます。キャンペーンは、UIユーザーがオーディエンスを配信する際に自動的に作成されます。APIでは、以前と同様にキャンペーンを作成して使用します。

APIについて知る

次の埋込みI/Oドキュメントを参照して、APIについての理解を深めることができます。I/Oドキュメントでは、各メソッドのパラメータについて説明し、コールのテンプレートを提供しています。ただし、ツールからライブAPIコールを実行することはできません。

次のリンクを新しいタブで開くと、I/Oドキュメントが3つのペインの形式で表示されます。

rules1.docs.apiary.io

このAPIの詳細は、My Oracle Support (MOS)にお問い合せください。

サービスURI

ルールAPIのURIは、次のとおりです。

services.bluekai.com/rest/taxonomyRuleChains

ルールの作成

ルールを作成するには、次のPOSTコールにリクエスト本文を含めます。

services.bluekai.com/rest/taxonomyRuleChains?partner.id={yourPartnerId}

ルールを作成するとき、問合せにパートナIDを指定し、リクエストのJSON本文にパラメータを含めます。パラメータによってルールが定義されます。指定するパラメータは、次のとおりです。

• rules: taxonomyRuleOperatorとtaxonomyRuleOperatorParamsの2つのパラメータで、ルールのロジックを定義します。
  • taxonomyRuleOperator: 使用するルール演算子のIDを入力します。ルール演算子は、次のいずれかの値になります。
    • 1 - (==) is: タグ(またはオフライン・ファイル)で渡されるphint値は、ルール内の値に完全にマッチする必要があります。
    • 3 - (_*) starts-with: phint値が、ルール内の値で始まる必要があります。
    • 4 - (*_ ) ends-with: 渡されるphint値が、ルール内の値で終わる必要があります。
    • 5 - (*_*) contains: phint値が、ルール内の値の中に含まれている必要があります。
  • taxonomyRuleOperatorParams: 値パラメータ(yourKeyおよびyourValue)のphintキーとphint値の名前を入力します。keyとvalue1のパラメータ名は変更しないでください。
    • キーの構文: phintキーは、英数字とアンダースコア(a-z、0-9および_)のみをサポートします。キーでは大/小文字は区別されません。キーにスペースを含めないでください。
    • 値の構文: phint値はすべてのLatin-1文字とUTF-8文字(英数字と特殊文字)をサポートします。値では大/小文字は区別されません。
    • URLベースのルールの作成: WebページのURLに対するルールを作成するには、yourKeyパラメータの__bk_lキーを入力します。参照URLに対するルールを作成するには、yourKeyパラメータの__bk_prキーを入力します。Oracle Data Cloudコア・タグにより、Webページから自動的にページURLとリファラURLが抽出されます。これにより、Webページとリファラに対してカテゴリをリンクできます。
• categories: このルールが適用されるカテゴリIDを入力します。
• sites: このルールが適用される1つ以上のサイトIDのリストを入力します。シート内のすべてのコンテナおよびサイトIDにルールを適用できるようにするには、このパラメータを空のままにしてpartnersパラメータにパートナIDを入力します。

• partners: シート内のすべてのコンテナおよびサイトIDにこのルールを適用できるようにするには、パートナIDを指定します。このルールのスコープを、sitesパラメータで指定されるサイトIDに制限する場合は、このパラメータを空のままにします。

  次の構文を使用して、パートナIDを指定します。

  "partners": ["id": "nnnnn"]

  例:

  "partners": ["id": "99999"]

サンプル・リクエスト本文

この例では、ルールはサイト48603に制限されます。

{
	"rules": [ {
		"taxonomyRuleOperator": { "id": 1 },
		"taxonomyRuleOperatorParams": [
			{ "name": "key", "value": "drink" },
			{ "name": "value1", "value": "banana_smoothie" }
		]
	} ],
	"categories": [ { "id": 1042249} ],
	"sites": [ { "id": 48603}], 
	"partners": []
}

この例では、このルールは、パートナ・シート99999が所有しているすべてのサイトに適用されます。

{
	"rules": [ {
		"taxonomyRuleOperator": { "id": 1 },
		"taxonomyRuleOperatorParams": [
			{ "name": "key", "value": "drink" },
			{ "name": "value1", "value": "banana_smoothie" }
		]
	} ],
	"categories": [ { "id": 1042249} ],
	"sites": [], 
	"partners": ["id": "P99999"]

}

レスポンス:

{
	"id": 31070824,
	"rules": [
		{
			"id": 33106879,
			"operatorExpression": "testKey=testValue",
			"taxonomyRuleOperator": {
				"id": 1,
				"name": "==",
				"formula": "{{key}}={{value1}}",
				"description": "is ",
				"createdAt": "2016-04-05T21:22:11-05:00",
				"updatedAt": "2016-04-05T21:22:11-05:00",
				"status": "active"
			},
			"taxonomyRuleOperatorParams": [
				{
					"name": "key",
					"value": "drink"
				},
				{
					"name": "value1",
					"value": "banana_smoothie"
				}
			]
		}
	],
	"categories": [
		{
			"id": 1042249,
			"name": "Banana Smoothie"
		}
	],
	"ruleChainMetaData": [],
	"classificationGroups": [],
	"sites": [
		{
			"id": 48603,
			"name": "Test"
		}
	],
		"partners": [],
		"createdAt": "2018-01-31T13:16:24-06:00",
		"updatedAt": "2018-01-31T13:16:24-06:00",
		"status": "active"
}

バルク・インポート(ファイル・アップロード経由)

TSVファイルまたはTXTファイルをアップロードして、同時に複数のルールを作成および編集するには:

1. ルールAPIに対するコールの問合せ文字列で、パスにimportを追加します。

   serviceUrl = 'https://services.bluekai.com/rest/taxonomyRuleChains/import?partner.id={yourPartnerId}'

2. headersパラメータで、Content-Typeをmultipart/form-dataに設定します。

   headers = {"Content-Type": "multipart/form-data; "Accept": "application/json","User-Agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0"}

3. インポートする.tsvまたは.txtファイルの名前に設定されるパラメータを含めます。
4. インポート・ファイルに次の列があることを確認します。
   

列	説明	アップロードで必須	アップロード経由でルールを作成する場合に値が必須
Action	この列に入力する値は、アクションに応じて異なります。 ルールの作成。空白のままにします。 ルールの編集。modifyと入力します。 ルールの削除。deleteと入力します。	○	×
Rule ID	ルールに対して生成されるユニークID。ルールを編集または削除する場合、これは必須です。	○(編集の場合)	×
Site ID	ルールが適用されるサイトIDのパイプ区切りリスト。ルールがすべてのサイトIDに適用される場合、P{partnerId}の構文のパートナID (P4021など)が表示されます。	○	○
Site ID Switch	内部使用のみ。あるサイトIDから収集されたデータを別のサイトIDに関連付ける場合、サイトIDスイッチが使用されます。これは、通常、サードパーティのオフライン・マッチ・パートナに使用されます。	○	×
Key1	phintキーの名前。phintキーでは大/小文字は区別されず、英数字とアンダースコア(a-z、0-9および_)がサポートされます。 phintキーのスペースはサポートされません。contains演算子を使用するルールを作成する場合は、phintキーにピリオド(.)を使用しないでください(正規表現の式を含むルールでは、キーが適切に評価されなくなります)。 複数のphintを持つルール: ルールに複数のphintが含まれる場合、エクスポートには各phintの追加のキー、演算子および値の列が含まれます。たとえば、ルールに3つのphintがある場合、エクスポートには、key2、Op2、Value2、key3、Op3およびValue3の列が追加で含まれます。	○	○
Op1	キーにリンクされたphint値を評価するために使用される演算子。これは、次のいずれかの値になります。 記号 名前 説明 == is タグ(またはオフライン・ファイル)で渡されるphint値は、ルール内の値に完全にマッチする必要があります。 *_* contains phint値が、ルール内の値の中に含まれている必要があります。 _* starts-with phint値の先頭が、ルール内の値の先頭である必要があります。 *_ ends-with 渡されるphint値の末尾が、ルール内の値の末尾である必要があります。 Oracleサービス・チームによって作成されるルールの場合、演算子は、次のいずれかの読取り専用の値になります。次の演算子は、Taxonomy Managerの将来のバージョンで、ルール作成に使用できるようになる可能性があります。 記号 名前 説明 [] range phint値が、指定された2つのphint値の範囲内に含まれる必要があります。 > greater than タグ内のphint値が、ルール内の値を超える必要があります。 < less than タグ内のphint値が、ルール内の値未満である必要があります。 >= greater than or equal タグ内のphint値が、ルール内の値以上である必要があります。 <= less than or equal タグ内のphint値が、ルール内の値以下である必要があります。 >,< greater than + less than タグ内の最初のphint値が、ルール内の最初の値を超える必要があり、かつ、タグ内の2番目のphint値が、ルール内の2番目の値未満である必要があります。 >,<= greater than + less than or equal タグ内の最初のphint値が、ルール内の最初の値を超える必要があり、かつ、タグ内の2番目のphint値が、ルール内の2番目の値以下である必要があります。 >=,< greater than or equal + less than タグ内の最初のphint値が、ルール内の最初の値以上である必要があり、かつ、タグ内の2番目のphint値は、ルール内の2番目の値未満である必要があります。 >=,<= greater than or equal + less than or equal タグ内の最初のphint値が、ルール内の最初の値以上である必要があり、かつ、タグ内の2番目のphint値が、ルール内の2番目の値以下である必要があります。	○	○
Value1	phint値。phint値はすべてのLatin-1文字とUTF-8文字(英数字と特殊記号)をサポートします。	○	○
Category ID	カテゴリに割り当てられているユニークID。バルク・アップロード経由でカテゴリを編集する場合、この列は必須となります。これは、Taxonomy Managerでは、一意のカテゴリIDに基づいてカテゴリを識別するためです。	○	○
Category Path	カテゴリのタクソノミのフルパス。バルク・アップロード経由でルールを伴うカテゴリを追加する場合、この列は必須となります。これは、Taxonomy Managerでは、タクソノミ・パスに基づいて、新しいカテゴリの作成場所を決定するためです。	×	×

バルク・インポートのデモ

サンプルのbulk_rules_import.py Pythonコードは、ルールAPIを使用してルールのバルク・インポートを実行する方法を示しています。このスクリプトの実行に必要なものは、次のとおりです。

• Python 2.7以上
• Requestsライブラリ1.2.3 (以上)

リクエスト・ライブラリのインストールに役立つPIP (Python Package Installationツール)を使用できます。PIPをダウンロードしてインストールするには、リクエスト・ライブラリをインストールしてPIPインストール・ファイルを削除し、コンソールに次のコマンドを入力します。

curl -O https://raw.github.com/pypa/pip/master/contrib/get-pip.py
sudo python get-pip.py
sudo pip install requests
rm get-pip.py

このスクリプトを実行するには、編集または作成するカテゴリを含む、rule_import.tsvという名前のTSVファイル(ダウンロード・テンプレート)を作成して、次のパラメータを指定する必要があります。

• url: 本番環境(services.bluekai.com)のURL
• verbosity: 印刷情報の一連の4つの詳細オプションを入力します。
• partnerid: ルールをアップロードしているシートに関連付けられたパートナID。
• bkuid: Webサービス・ユーザー・キー
• bksecretkey: Webサービス秘密キー

次の例は、このスクリプトをコールするために必要な構文を示しています。

bulk_rules_import.py --url https://services.bluekai.com -v -v -v -v --partnerid BlueKai Partner ID--bkuid WebServiceUserKey --bksecretkey WebServicePrivateKey

ルールのバルク・インポートの例:

#! /usr/bin/env python -B
# -*- coding: utf-8 -*-
import sys, requests, json, argparse, unittest, hmac, base64, urllib, urlparse, hashlib
def cli_options():
    parser = argparse.ArgumentParser(description='Demo for Rule REST API')
    parser.add_argument('-u','--url', default='https://localhost:8080/', help='Web service base URL')
    parser.add_argument('-p','--partnerid', help='Partner id to use with this request')
    parser.add_argument('-i','--bkuid', default='', help='BlueKai UID')
    parser.add_argument('-k','--bksecretkey', default='', help='BlueKai Secret key')
    parser.add_argument('-v','--verbose', default=0, action='count', help='Prints additional information')
    return parser.parse_args()
args = cli_options()
URL = args.url.strip()
BKUID = args.bkuid
BKSECRETKEY = args.bksecretkey
PARTNERID = args.partnerid
VERBOSITY = args.verbose
USER_AGENT = {'User-Agent':'Mozilla/5.0 (Macintosh; Intel Mac OS X 10.8; rv:22.0) Gecko/20100101 Firefox/22.0'}
JSON_HEADERS = {'Content-Type': 'multipart/form-data', 'Accept':'application/json'}
COMMON_HEADERS = dict(USER_AGENT.items() + JSON_HEADERS.items())
class RuleRest():
    res = False
    def info(self, message, verbosityLevel = 1):
        if VERBOSITY >= verbosityLevel:
        if not isinstance(message, basestring):
            print json.dumps(message, indent=4)
    else:
        print message
    def prepare_headers(self, headers = None):
        if headers is None:
            return COMMON_HEADERS.copy()
        else:
            return dict(COMMON_HEADERS.items() + headers.items())
    def parse_query_params(self, query):
        parameterList = query.split('&')
        params = {}
        if len(parameterList) > 0:
            for entry in parameterList:
                kvPair = entry.split('=')
                params[kvPair[0]] = kvPair[1] if len(kvPair) > 1 else '';
        return params
    def prepare_request(self, endpoint, method = 'GET', params = None, data = None, headers = None, files = None, sign=True):
        if files is not None:
            headers.pop('Content-Type', None)
        req = requests.Request(method, URL + endpoint, data = data, headers = headers, files = files)
        prepared = req.prepare()
        if sign:
            if params is None:
                params = {}
 
            parsedUrl = urlparse.urlparse(URL)
            parsedEndpoint = urlparse.urlparse(endpoint)
            servletPath = "" if parsedEndpoint.path.strip().startswith("/") else "rest/"
            urlPath = parsedUrl.path.strip('/')
            if urlPath:
                urlPath = urlPath + '/'
            fullPath = '/'+ urlPath + servletPath + parsedEndpoint.path.strip('/')
            stringToSign = method + fullPath
 
            params = dict(params.items() + self.parse_query_params(parsedUrl.query).items() + self.parse_query_params(parsedEndpoint.query).items())
            queryParameterStr = '';
            for key in params.keys():
                if len(key) > 0:
                    if isinstance(params[key], list):
                        for listItem in params[key]:
                            value = urllib.quote(str(listItem))
                            stringToSign += value
                            queryParameterStr += urllib.quote(key) + '=' + value + '&'
                    else:
                        value = urllib.quote(str(params[key]))
                        stringToSign += value
queryParameterStr += urllib.quote(key) + '=' + value + '&'
            if prepared.body is not None:
                stringToSign += prepared.body
            h = hmac.new(BKSECRETKEY, stringToSign.strip(), hashlib.sha256)
            s = base64.standard_b64encode(h.digest())
            signature = urllib.quote_plus(s)
 
            finalURL = parsedUrl.scheme + '://' + parsedUrl.netloc + fullPath + '?' + queryParameterStr + 'bkuid=' + BKUID + '&bksig=' + signature
        else:
            finalURL = URL + endpoint
 
        self.info('Sending %s request to: %s' %(method, finalURL))
        prepared.url = finalURL
        if VERBOSITY >=4:
            print "Request object:"
            for key, value in prepared.headers.iteritems():
                print "%s: %s" % (key, value)
            if prepared.body is not None and len(prepared.body)>0:
                print ""
                print prepared.body
        return prepared
    def post(self, endpoint, payload = None, params = None, headers = None, files = None):
        if payload is not None:
            data = payload if isinstance(payload, basestring) else json.dumps(payload)
        else:
            data = None
        self.res = requests.Session().send(self.prepare_request(endpoint, method = 'POST', params = params, data = data, files = files, headers = self.prepare_headers(headers)), verify = False)
        return self
    def test_bulk_rule_rest_create(self):
        files = {'file': open('rule_import.tsv', 'rb')}
        created_rules = self.post('taxonomyRuleChains/import', files = files, params={'partner.id':PARTNERID}).res.json()
        self.info(created_rules, 2)
instance=RuleRest()
instance.test_bulk_rule_rest_create()

ルールの更新

ルールを更新するには、PUTコールに、パートナID、ルールIDおよび更新するパラメータを指定したリクエスト本文を含めます。

サンプルPUTリクエスト:

https://services.bluekai.com/rest/taxonomyRuleChains/?partner.id={yourPartnerId}

マルチバイト文字を含むルール

マルチバイト・エンコーディングを含むURLのルールを作成するには、UTF-8エンコード文字でパーセント記号(%)をエンコードする必要があります。たとえば、https://www.マネジメント/site.htmlのURLルールを作成するには、「マネジメント」をUTF-8に変換し、その結果、次のエンコーディングになります。

%e3%83%9e%e3%83%8d%e3%82%b8%e3%83%a1%e3%83%b3%e3%83%88

UTF-8エンコーディングでパーセント記号をエンコードし(%記号をそれぞれ%25に変換します)、その結果、次のエンコーディングになります。

%25e3%2583%259e%25e3%2583%258d%25e3%2582%25b8%25e3%2583%25a1%25e3%2583%25b3%25e3%2583%2588

これにより、エンコード後の文字列は、次のようになります。

https://www.com%2F%25e3%2583%259e%25e3%2583%258d%25e3%2582%25b8%25e3%2583%25a1%25e3%2583%25b3%25e3%2583%2588%2Fsite.html

関連項目: パーセントエンコーディング

関連するAPIコール

次に、通常、ルールAPIを使用する前に実行するAPIコールを示します。

次に、通常、タクソノミ・ルール・チェーンAPIを使用した後に実行するAPIコールを示します。

GETレスポンスのサマリー

タクソノミ・ルール・チェーンAPIのGETリクエストでは、カテゴリをサイト・データおよびオフライン・データにマッピングするために使用されるルールが返されます。次に、各ルールに含まれるプロパティを示します。

POSTレスポンスのエラー

カテゴリを作成するPOSTリクエストが失敗した場合、POSTレスポンスでは次のいずれかのコードが使用されます。

POSTレスポンスの本文には、次に示す、エラーの原因となる各入力属性のエラー・コードのリストが含まれます。

さらに学ぶ

カテゴリAPI

Taxonomy Manager

パーセントエンコーディング