Containers API
You can implement the Oracle Data Cloud containers web service to create and manage the individual sites in the Oracle Data Cloud platform. Creating a container generates a site ID, which is a unique ID for managing a site. Your DMP can have multiple containers, and each container will be associated with a unique site ID. The container and site ID are used for ingesting data into the Oracle Data Cloud platform and delivering data back to your site.
Note: Users no longer create campaigns in the Oracle Data Cloud platform UI. The campaign workflow is now part of the audience workflow. The platform still uses campaigns to manage audience data delivery however. They are created automatically when a UI user delivers an audience. In the APIs, you create and use campaigns as before.
In this topic
Explore the API
The embedded I/O doc below enables you to explore the API. The I/O doc explains the parameters for each method and provides templates for your calls. You cannot make live API calls from the tool, however.
Open the link below in a new tab to see the I/O doc in a three-pane format.
For help with this API, contact My Oracle Support (MOS).
Service URI
The URI for the containers API is:
services.bluekai.com/Services/WS/sites
Related API calls
Here are the API calls you will typically make after you use the containers API:
| Post-containers API call | Use Case |
|---|---|
| Categories API | Independently add first-party categories to your private taxonomy that represent the user attributes being collected with your container |
| Rules API | Independently create classification rules that map the user attributes collected by your container with your categories. |
| Schedules | Specify where, when, and for whom third-party tags are fired from a container. |
Use cases
Using the container and site ID for data ingest
You can use a container and its site ID to transfer user data into the Oracle Data Cloud platform.
A site ID is a unique identifier that enables your site to be managed in the Oracle Data Cloud platform.
You can create a container with the containers API and then use the container tool in the platform UI to add the JavaScript and HTML tag code. The code collects data from your site and transfers it to the platform. The data may be classification attributes or unique user IDs (UUIDs) that are used for ID swapping. The container is required for all data ingest methods:
Data Providers Onboarding EU Data. To ingest data for user profiles located in the European Union (EU), you must have signed Oracle's General Data Protection Regulation (GDPR) Consent agreement. If you have not signed the agreement, but you make a Containers API POST or PUT request with the container configured for one or more EU countries, the Containers API will return an error and your container will not be created. Contact your Oracle Account Representative to obtain and sign the agreement.
Using the container and site ID for data delivery
You can use your site ID to deliver user data.
You can create a container with the containers API, insert the generated site ID into your regex pixel if you are delivering data via Server Data Transfer, and then use the pixel URL API to associate your campaigns with a destination.
You can also use a container with a JSON Return tag type to deliver your campaign data directly to the Web page that is hosting the tag.
GET response summary
The containers API GET request returns a container or a list of containers.
| Property | Type | Description |
|---|---|---|
allowed_buyers
|
object | If transaction_scope is set to "permissioned", this object lists the id and name of the buyers that may win on this site; otherwise, this is an empty list.
|
analytics_only
|
boolean | Indicates whether the site is used for analytics only (true) or just for data collection (false) |
country_list_type
|
enum | Indicates whether the countries in the blocked_countries list are in a WHITELIST or BLACKLIST. The default is BLACKLIST. |
blocked_countries
|
list | A list of the two-letter ISO 3166-1 alpha-2 country code of the countries for which data collection is whitelisted or blacklisted based on users' IP addresses. Netherlands (NL) is blocked by default for new containers. If you use a whitelist, this field must contain at least one country. In the future, this field will be renamed to |
created_at
|
date | A timestamp indicating when the site was created. |
data_transfer_boost_enabled
|
boolean | Specifies whether the container tag is re-fired every n seconds after the initial page load while the user is still on the page (true). This enables you to increase the number of third-party pixels that can be fired from the container, while exceeding the auction slot limit, but without affecting the performance of your page. The container tag can be re-fired a maximum of 15 times. The frequency in which the container tag is re-fired is based on the data transfer interval.For example, if you set the default auction limit to 10, enable data transfer boost, set the data transfer interval to 7 seconds, and you add 30 third-party pixels to the container, the following will occur:
true). |
data_transfer_boost_interval
|
int | Specifies how frequently (in seconds) the container tag is re-fired if you set the data_transfer_boost_enabled flag to true |
data_transfer_limit_range
|
int | The maximum number of slots available in the container for firing image tags. For data providers, this is the number of slots available for selling data or executing an ID swap. For DMP clients, this is the number of slots available for delivering first-party data to partners. |
group_id
|
integer | The unique ID assigned to the site's group. A group contains both the desktop and mobile versions of the site. |
id
|
integer | The site ID generated when the container was created. This is a unique identifier used to manage your individual Web sites (for example, if you have separate Web sites for different countries). |
name
|
string | The name of your site |
partner
|
object | An object containing your partner-based id and name.
|
private_data
|
boolean | Indicates whether the data collected from your site is private use and cannot be sold to any partner that you have not whitelisted (1), or it can be sold to any partner in the public Oracle Data Marketplace (0) |
redirect_domains
|
array | Specifies a list of valid URL strings used to whitelist domains to which the site can redirect. Oracle Data Cloud domain calls (tags.bluekai.com) that include redir key-value pair parameters are evaluated against this site domain whitelist before they are permitted to redirect.Example: "redirect_domains" : ["www.google.com", "www.facebook.com"] |
transaction_scope
|
string | Indicates which of your whitelisted buyers can win on this site. This may be one of the following values:
|
type
|
string | The type of site, which may be either 0 for desktop or 1 for mobile |
updated_at
|
date | A timestamp indicating when the site was last modified |
Updating the tag redirect domains whitelist
The redirect_domains property includes the container's tag redirect domains whitelist. You can modify the attached sample_containers_redir.py Python script to update the container's whitelist by replacing the following placeholders with the correct values for your use case:
{YOUR_SITE_ID}: The site ID generated when the container was created{YOUR_WEB_SERVICE_USER_KEY}: Your web service user key{YOUR_WEB_SERVICE_PRIVATE_KEY}: Your web service private key{YOUR_REDIRECT_DOMAINS}: A comma-separated list of tag redirect domains that you want to whitelist. The domains must be enclosed in double quotes (""). For example:"www.google.com", "www.oracle.com", "www.facebook.com", "www.twitter.com"
The curly braces ({}) in the script indicate placeholder values that you need to replace.
The script makes a GET request to the containers API to pull your site details and then makes a PUT request to update the site with the redirect domains that you entered.
Updating blocked countries
You can update the countries from which data collection is blocked using the containers API. To do this, make a PUT request with the site ID to be updated in the URL, and the country_list_type set to WHITELIST or BLACKLIST depending on the desired configuration, and the list of two-letter ISO 3166-1 alpha-2 country codes to be blocked in the blocked_countries field within the JSON body. The following code example demonstrates how to create a container that blocks data collection in the EU (note that curly braces {} indicate placeholders for values you need to fill in):
Expand to see the sample code
#!/usr/bin/python
import os
import sys
import urllib
import urllib2
import cookielib
import urlparse
import hashlib
import hmac
import base64
import json
import random
headers = {"Accept":"application/json","Content-type":"application/json","User_Agent":"Mozilla/5.0 (Macintosh; U; Intel Mac OS X 10.6; en-US; rv:1.9.1) Gecko/20090624 Firefox/3.5"}
serviceUrl = 'https://services.bluekai.com/Services/WS/sites/{YOUR_SITE_ID}'
# Add your user id and key
bkuid = '{YOUR_WEB_SERVICE_USER_KEY}'
bksecretkey = '{YOUR_WEB_SERVICE_PRIVATE_KEY}'
## Example PUT data
## Enter list of countries where data collection is blocked
data = "{\"country_list_type\": \"BLACKLIST\", \"blocked_countries\": [\"EU\"]}"
def signatureInputBuilder(url, method, data):
stringToSign = method
parsedUrl = urlparse.urlparse(url)
print parsedUrl
stringToSign += parsedUrl.path
# first split the query into array of parameters separated by the '&' character
print parsedUrl.query
qP = parsedUrl.query.split('&')
print qP
if len(qP) > 0:
for qS in qP:
qP2 = qS.split('=', 1)
#print qP2
if len(qP2) > 1:
stringToSign += qP2[1]
print stringToSign
if data != None :
stringToSign += data
print stringToSign
h = hmac.new(bksecretkey, stringToSign, hashlib.sha256)
s = base64.standard_b64encode(h.digest())
print s
u = urllib.quote_plus(s)
print u
newUrl = url
if url.find('?') == -1 :
newUrl += '?'
else:
newUrl += '&'
newUrl += 'bkuid=' + bkuid + '&bksig=' + u
return newUrl
def doRequest(url, method, data):
try:
cJ = cookielib.CookieJar()
request = None
if method == 'PUT' :
request = urllib2.Request(url, data, headers)
request.get_method = lambda: 'PUT'
elif method == 'DELETE' :
request = urllib2.Request(url, data, headers)
request.get_method = lambda: 'DELETE'
elif data != None :
request = urllib2.Request(url, data, headers)
else:
request = urllib2.Request(url, None, headers)
# request.add_header('If-Modified-Since' , 'Fri, 31 Aug 2012 14:01:51 PDT')
opener = urllib2.build_opener(urllib2.HTTPCookieProcessor(cJ))
u = opener.open(request)
rawData = u.read()
print rawData
print "200 ok"
return rawData
except urllib2.HTTPError, e:
print "HTTP error: %d %s" % (e.code, str(e))
print "ERROR: ", e.read()
return None
except urllib2.URLError, e:
print "Network error: %s" % e.reason.args[1]
print "ERROR: ", e.read()
return None
# Comment and uncomment both lines for your request
def main(argv=None):
#newUrl = signatureInputBuilder(serviceUrl, 'GET', None)
#newUrl = signatureInputBuilder(serviceUrl, 'POST', data)
newUrl = signatureInputBuilder(serviceUrl, 'PUT', data)
print newUrl
#doRequest(newUrl, 'GET', None)
#doRequest(newUrl, 'POST', data)
doRequest(newUrl, 'PUT', data)
if __name__ == "__main__":
main()
Sample Python script for updating the tag redirect domains whitelist