Dwb Query API
-
Upload
xiang-an-xie -
Category
Documents
-
view
7 -
download
1
description
Transcript of Dwb Query API
![Page 1: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/1.jpg)
Adobe® Marketing Cloud
Data Workbench Query API
![Page 2: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/2.jpg)
Contents
Data Workbench Query API.............................................................................................3Administration of Data Workbench Query API.......................................................................................................3
Licensing.........................................................................................................................................................................................................3
Enabling and Disabling API Requests..................................................................................................................................................3
Access Control..............................................................................................................................................................................................4
Load Balancing.............................................................................................................................................................................................4
Using a Query API Proxy...........................................................................................................................................................................5
Using the Data Workbench Query API.......................................................................................................................5
Request Types...............................................................................................................................................................................................5
The Data Workbench Query Language...............................................................................................................................................6
Output Formats............................................................................................................................................................................................7
The HTTP Protocol.......................................................................................................................................................................................8
Query API Reference.......................................................................................................................................................12
Schema Request formats.......................................................................................................................................................................12
Data Request Formats.............................................................................................................................................................................14
Response Status Line...............................................................................................................................................................................17
Server Configuration...............................................................................................................................................................................17
Sample Clients...........................................................................................................................................................................................18
Contact and Legal Information..................................................................................................................................18
Data Workbench Query APILast updated 12/19/2013
![Page 3: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/3.jpg)
Data Workbench Query APIThe processed results of a dataset are usually made available through the graphical user interface of the data workbench clientand report server.
However, if you want access to results in their raw form for use in other ways, you can use the Query API to query a single DPUand return the results across all DPUs.
To use the API, a client sends an HTTP request to the data workbench server. This requires administration to license the API,enable API requests, balance the data load, and set up access control rights or a proxy server.
Administration of Data Workbench Query API
Follow these basic steps to implement the data workbench query API.
Licensing
The data workbench Query API is only enabled by the server if the server's certificate (server_cert.pem in the server'sCertificates folder) includes the line:
Product = Query API
If the server is not licensed for the API but the API is enabled (see Enabling and Disabling API Requests), then the following lineshows in the server's trace log when the server starts or when a profile is reprocessed:
Not enabling Query API (not licensed)
If your server license does not include a Query API line, please contact Adobe ClientCare.
Only one server with a Query API license is required when installing to a server cluster. However, if heavy query traffic is expectedusing the Query API, then sending all queries to a single server may overload that server.
Enabling and Disabling API Requests
By default, each server will enable the data workbench Query API if the server has been licensed.
When licensed, the line
Enabling Query API (licensed)
shows in the server's trace log.
To disable the API service for each profile, simply add the line:
Enable Query API = bool: false
in the Server.cfg file in the Dataset folder of the profile.
When the previous line is present, the following line shows in the trace log:
Not enabling Query API (disabled in Server.cfg)
The following is an example:Server = ServerConfig: Enable Query API = bool: false Sample Bytes = double: 250e6
3Data Workbench Query API
![Page 4: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/4.jpg)
Access Control
Data workbench access control applies to API requests with the same requirements as all other services.
API requests are sent to either of the following URIs:
http://<server>/Profiles/<profile>/API.query
or
https://<server>/Profiles/<profile>/API.query
• <server> is the DNS name or IP address (and, optionally, the port number) of the data workbench server.• <profile> is the name of the profile.
For example, the following entry in Access Control.cfg lets users access the data workbench query API if they connectusing SSL, and the OU (Organizational Unit) field of their trusted certificate is set to Insight (data workbench) API Users. Seethe example below:0 = AccessGroup: Members = vector: 1 items 0 = string: OU:Insight API Users Name = string: All Insight API users Read-Only Access = vector: 0 items Read-Write Access = vector: 1 items 0 = string: /Profiles/MyProfile/API.query
Note: Refer to the Data Workbench Server Installation and Administration Guide for information about controlling accessto the data workbench server URI's.
Since the API provides full access to your company's data, proper access control is extremely important. The proper choice ofaccess control means whether group membership is defined by IP address, certificate fields such as CN or OU, and so on, dependson the circumstances, including, but not limited to, whether the requests are done through the internet or within the confinesof a protected private network.
If the data workbench servers and the end users are all inside a firewall, access control using IP address may be acceptable.However, under other circumstances, especially if the data workbench server needs to be accessed through the Internet, usingSSL and trusted certificates is absolutely required.
In some installations, setting up all your users' browsers to use trusted certificates may be impractical. A recommended solutionis to use a Query API Proxy.
Load Balancing
In a cluster, each licensed and enabled server can respond to API queries.
See Enabling and Disabling API Requests. The work of computing the query results is divided among all of the servers in thecluster. However, the server that received the query directly is burdened more than the other servers for both CPU and memoryusage.
When heavy API query traffic is expected—or when server status indicates that the API query server is significantly more heavilyloaded than the other servers in the cluster—it is advisable to balance the traffic load. For the Query API in data workbench,load balancing means directing API queries evenly to all servers in the cluster.
If clients connect directly to the API server, then two different types of mechanisms can be used:
Instruct users to employ different servers within the cluster when running a query. This is the simplest way to load balance.
4Data Workbench Query API
![Page 5: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/5.jpg)
Give the client software a list of all servers in the cluster, then program it to select a different target server for each query (in arandom sequence).
If an API proxy is used, then employ Method 2 for load balancing. See Using a Query API Proxy.
Using a Query API Proxy
An API proxy is a web server (typically, a common HTTP server), which implement its own secure authentication scheme.
Most companies already have such a web server for use by their employees. The server receives requests from authenticatedusers and forwards them to the data workbench server. The proxy server makes the API query requests using SSL and a trustedcertificate.
A trusted certificate is issued by a CA listed in the trust_ca_cert.pem certificate, and found in the data workbench server'sCertificates folder.
In the Certificates folder there is a certificate called trust_ca_cert.pem, which contains a list of many well knownCertificate Authorities (CA). Any certificate you have is trusted if issued by one of those CA's.
An additional benefit of using an API proxy is the opportunity for the proxy to isolate the end user from the Query API protocol.
For example:
1. The server receives a regular HTTP request from the end user's browser:
(https://insight.mycompany.com/dashboard?date=yesterday).
2. The server submits the appropriate query to the data workbench query API.3. Search results are then formatted into HTML and returned to the user.
Using a Query API Proxy provides advantages over accessing the Query API directly using client-side javascript in the user'sbrowser. Client-side access through javascript is subject to browser exclusion of cross-domain scripting. This means that theweb server serving the page that contains the javascript should be on the same domain as the data workbench server, which isnot always practical.
Using the Data Workbench Query API
This section provides general information for employing the data workbench API Query including its request types, the querylanguage, output formats, and HTTP protocols.
In most cases, the body of the request consists of text written in the data workbench Query Language. It is assumed that you arefamiliar with the HTTP protocol. Users not familiar with HTTP may still be able to use the data workbench Query API throughone of the sample clients provided. See Sample Clients.
An API request is always related to a single profile.
Request Types
Two types of API requests are understood by the data workbench server:
• A Schema Request provides information about the dataset schema configured for the profile, similar to the informationdisplayed in the Dataset Schema visualization in the data workbench client. Please refer to the data workbench Client Guideand Dataset Configuration Guide for details.
• Data Requests query the server about the data processed.
5Data Workbench Query API
![Page 6: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/6.jpg)
The data workbench Query API does not provide support for administration of the data workbench server. Although a handfulof metrics can be queried to provide a limited amount of information about the processing state of the server, any extensiveadministrative functionality is beyond the scope of this component.
Note: The API implemented in Insight 5.4 is not backwards compatible with previous versions. Any client code written forprevious versions of data workbench must be modified in order to be used with servers running the Insight 5.4 code.
The Data Workbench Query Language
This section describes the syntax and semantics of the data workbench Query Language.
The reader is assumed to be familiar with programming languages as well as with the terminology used to describe them.
Notation:
1. underlined words should be entered in the query text literally.2. UPPERCASE_WORDS represent the type of expression that should be used.3. The form {text}? represents optional text.
The data workbench Query Language is only used for Data Requests (not Schema Requests).
A query in the data workbench Query Language is a sequence of statements, each of which is either a definition statement or aquery statement. Each statement is terminated with a semicolon. White space is ignored outside of keywords, identifiers andstring literals.
A definition statement is used to define and name dimensions, metrics and filters. A collection of these objects is already initializedby the dataset configuration, and the Query Language definitions are used to add or override these definitions.
A query entity (dimension, metric or filter) defined in a definition statement is available for use in subsequent query statements(but only within the same request).
A definition statements has one of the following three forms:dim NAME = DIM_EXPR;metric NAME = METRIC_EXPR;filter NAME = FILTER_EXPR;
Dimensions, metrics and filters have separate name spaces, so a dimension, a metric, and a filter can have the same name andstill be recognized as distinct entities by the parser. (However, same names might confuse a person reading the code, and is notrecommended.)
For the syntax of DIM_EXPR, METRIC_EXPR and FILTER_EXPR, please refer to Query Language Syntax in the client guide.
Two kinds of queries can be described by a query statement:
• A Dim Query requests information about the current number and names of the elements of a dimension. The syntax of a DimQuery is:list DIM_EXPR {as STRING}? ;
• A Metric Query requests the result of evaluating a set of metrics over a dimension, optionally applying a given filter. The syntaxof a Metric Query is:eval METRIC_LIST over DIM_EXPR {as STRING}? ;
The optional "as STRING" clause in each of the query statement types assigns the given string as an alias for the dimension. Thisalias is used in the output, instead of the dimension's actual name. Using an alias allows outputting descriptive dimension names,which are not valid as identifiers within the API. A METRIC_LIST is one or more METRIC_EXPRs, separated by commas.
6Data Workbench Query API
![Page 7: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/7.jpg)
Example
The following example shows a definition statement, two dim query statements and a metric query statement:dim WeekdayXReferrer = cartesian product(";", Day_of_Week, Referrer);list Referrer;list WeekdayXReferrer as "Weekday;Referrer";eval Visitors, Sessions over WeekdayXReferrer as "Weekday;Referrer";
About Report Time Dimensions
Report Time dimensions are defined in a dataset's configuration files and cannot be used as is in an API query. Report Timedimensions are those derived from the LastNDim, HoursOfLastDay or DaysOfLastMonth, and rely on the ReportTime metric.To use a Report Time dimension in an API query, it must be defined (or redefined) within the Query Language text. To facilitatesuch definition, the following dimensions and metrics are provided:
• Dimensions
• last n• days of previous months• days of current month• days of future months• hours of day
For details, refer to Query Language Syntax in the client guide.
• Metrics
• Now - A predefined Constant Metric, whose value is the time at which the query was parsed.• As_Of - This metric, which is generally available, is useful to refer to the latest time up to which all data has been processed.
Comments
The Query Language syntax does not currently support embedding comments within the query text.
Output Formats
The result provided in response to an API query can be formatted in one of a variety of formats.
The table below lists the formats currently supported.
See Schema Request Formats and Data Request Formats for the details of the representation in each format.
DescriptionFormat
All results are formatted as text, which is human readable and can be directly presented to the user. Thisformat is moderately space efficient.
Text
Numeric values are transmitted in their binary representation. This format is the most space efficient, and isalso the most efficient to create on the server side, and if the client wants to use numeric data for computations,
Binary
it can do so without having to parse the text. Supported for Data Requests only. All numeric values arerepresented as floating point numbers in the IEEE REAL*8 format, Little Endian byte order.
This format is the least space efficient, but is provided for the convenience of clients which use existing facilitiesto parse XML and convert them to native objects.
XML
7Data Workbench Query API
![Page 8: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/8.jpg)
DescriptionFormat
Somewhat more efficient than XML. Provide for the convenience of clients which have existing facilities forparsing JSON.
JSON
The HTTP Protocol
The following sections identify responses and requests from the Query API.
API Server URI
An API request is always related to a single profile. API requests are sent to:
http:// <server> /Profiles/ <profile> /API.query or https:// <server> /Profiles/ <profile>/API.query
where <server> is the DNS name or IP address of the data workbench server and <profile> is the name of the profile. If acluster of servers is used, any of the DPUs in the cluster may be used. If many queries are submitted to a heavily loaded cluster,spread the queries evenly among the servers in the cluster, if practical.
API requests contain parameters in the HTTP request headers, or, alternatively, in the request's query string. Data requestscontains the query text in their body.
The response to an API request contains some information in the response headers. Most of this information is also availablewithin the response body. The actual results, if any, are returned in the response body.
Header names and their query string key equivalents are case sensitive, but their values are not, unless otherwise specified.
Response Status Line
Upon success, the server's response contains a status line of 200 OK. If a request is not valid, or if the server encountered anerror condition when trying to provide the response, a status line indicating the nature of the error is returned. See ResponseStatus Line.
Schema Requests
A Schema Request can be sent to the server as soon as the server has finished loading its configuration, and the result is sentimmediately in the HTTP response.
The parameters used in a Schema Request are:
DefaultRequiredValuesDescriptionQuery String KeyHeader
Yesget-schemaType of requestActionX-Action
textNotextFormat of resultFormatX-Format
xml
xml-flat
json
json-flat
8Data Workbench Query API
![Page 9: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/9.jpg)
A Schema Request's body is left empty.
No special headers are used in the response to a schema request.
The result is returned as the body of the HTTP response to this request. See Schema Request Formats for additional information.
Data Requests
A data request provides a snapshot of the data processed by the server at a given time. Because updates for this snapshot mightbe desired, data is requested using a three phase protocol:
1. Create Request: Sends the query to the server, which creates an internal query object. The response to this request includesa unique Query ID, which is used later to refer to it in Result and Drop Requests. Multiple query objects may be created bymultiple Create Requests and retained by the server, each of which can be later referred to, using its Query ID.
2. Result Request: The client returns a snapshot of the results for the query identified by its Query ID. This can be repeatedindefinitely. If more than one query has been created, Result Requests for any or all of them can be interleaved arbitrarily(but each Result Request can only refer to a single Query ID).
3. Drop Request: The client sends a Drop Request when instructed. At this point the server destroys the query object and stopscalculating results for it, releasing the resources that are tied up in the calculation. The server also drops the requestautomatically if no Result Request has been received for a given query for a period of five minutes.
A Create Request may be combined with a Result Request, so that the response to the Create Request contains the [first] result.In this case, the request is referred to as a CreateWait Request.
Create Requests
The parameters used in a Create Request are:
DefaultRequiredValuesDescriptionQuery String KeyHeader
YescreateType of requestActionX-Action
textNoNoFormat of result. (Note:a subsequent Result
FormatX-Format
Request can override thisvalue.)
The body of the request contains the text of the query, which is expressed in the data workbench Query Language. See The DataWorkbench Query Language.
The response is returned immediately, without any query results.
The headers used in the response to a Create Request are:
When PresentDescriptionHeader
AlwaysA unique query identifier to be used in subsequent Result and Drop Requests.X-Query-ID
The body of the response to a Create Request consists of a single line, containing the Query-ID parameter to be used in subsequentResult and Drop requests. It is identical to the value of the X-Query-ID response header. Regardless of the requested resultsformat, this item is the only content of the body (not enclosed in XML tags or JSON syntax) and is always represented as text(not binary).
9Data Workbench Query API
![Page 10: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/10.jpg)
Result Requests
The parameters used in a Result Request are:
DefaultRequiredValuesDescriptionQuery StringKey
Header
YesresultType of requestActionX-Action
YesThe value of theQuery-ID parameter
Identifies the query for whicha result is requested.
Query-IDX-Query-ID
returned by the serverin the response to theCreate or CreateWaitRequest.
Value specified inCreate Request.(Otherwise text)
Notext
xml
json
Format of result. (Note thatthis value will override thevalue specified in the CreateRequest, if any.)
FormatX-Format
binary
1.0NoA number in the range[0.0, 1.0] (inclusive)
The minimum completionlevel at which results will bereturned. A value of 0 will
CompletionX-Completion
always return the resultsimmediately.
The body of a Result Request is left empty.
The parameters used in the response to a Result Request are:
When PresentDescriptionHeader
AlwaysThe actual completion level of the results returned (Should always begreater than or equal to the value of the X-Completion header in therequest.)
X-Completion
If the status is "500 QueryError".
Additional information about the internal server error which caused a"500 Query Error" status.
X-Error
The body of the response to a Result Request contains the result. See Data Request Formats for more information.
CreateWait Requests
The parameters used in a CreateWait Request are:
DefaultRequiredValuesDescriptionQuery String KeyHeader
YescreatewaitType of requestActionX-Action
textNotextFormat of result. (Notethat this value will override
FormatX-Format
10Data Workbench Query API
![Page 11: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/11.jpg)
DefaultRequiredValuesDescriptionQuery String KeyHeader
xmlthe value specified in theResult Request.) json
binary
1.0NoA number in the range[0.0, 1.0] (inclusive)
The minimum completionlevel at which results willbe returned.
CompletionX-Completion
This parameter affects thisrequest only, notsubsequent ResultRequests.
A value of 0 means thatresults will be returnedimmediately, regardless ofthe completion level of thequeries.
The body of the request contains the text of the query, which is expressed in the data workbench Query Language. See The DataWorkbench Query Language.
The response is delayed until the (explicit or implicit) value of the completion parameter is reached, and the body of the responsecontains the result.
The headers used in the response to a CreateWait Request are:
When PresentDescriptionHeader
AlwaysA unique query identifier to be used in subsequent Result and Drop Requests.X-Query-ID
AlwaysThe actual completion level of the results returned. (Will always be greaterthan or equal to the value of the X-Completion parameter in the request).
X-Completion
The body of the response to a CreateWait Request contains the results. See Data Request Formats for more information.
Drop Requests
The parameters used in a Drop Request are:
DefaultRequiredValuesDescriptionHeader
yesdropType of requestX-Action
yesThe value of the X-Query-ID headerreturned by the server in the response to theCreate Request.
Identifies the query to bedropped
X-Query-ID
11Data Workbench Query API
![Page 12: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/12.jpg)
Query API Reference
The following appendixes provide request formats for the schema.
Schema Request formats
Text Format (X-Format: text)
The text format lets the client treat this data as a flat list of dimensions or to construct a hierarchical structure thereof.
The schema is represented as comma separated text, one dimension per line. Each line has four items:
DescriptionNameColumn
The name of this dimension.Name1
The name of the parent dimension (possibly empty, for a root dimension).Parent2
countable, simple, manyToMany or denormal.Relationship3
The type (class) of the dimension.Type4
XML Format (X-Format: xml)
The schema is represented hierarchically as XML. The following tags are used:
Child NodesAttributesDescriptionTag
Zero or more <DIM> tagsnoneTop level.<SCHEMA>
zero or one of each of the following<*_CHILDREN> tags:
name
type
Describes a dimension andits children.
<DIM>
<SIMPLE_CHILDREN>
<COUNTABLE_CHILDREN>
<MANY_TO_MANY_CHILDREN>
<DENORMAL_CHILDREN>
One or more <DIM> tagsnoneAll the simple children ofthe containing <DIM> node
<SIMPLE_CH ILDREN>
One or more <DIM> tagsnoneAll the countable childrenof the containing <DIM>node
<COUNTABLE_CHILDREN>
One or more <DIM> tagsnoneAll the many-to-manychildren of the containing<DIM> node
<MANY_TO_MANY_CHILDREN>
12Data Workbench Query API
![Page 13: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/13.jpg)
Child NodesAttributesDescriptionTag
One or more <DIM> tagsnoneAll the denormal childrenof the containing <DIM>node
<DENORMAL_CHILDREN>
XML Flattened Format (X-Format: xml-flat)
This format is similar to the XML format, except <DIM> nodes do not contain children tags - all the <DIM> tags are containeddirectly in the top level <SCHEMA> tag.
Child NodesAttributesDescriptionTag
Zero or more <DIM> tagsnoneTop level<SCHEMA>
nonenameDescribes a dimension<DIM>
type
JSON Format (X-Format: json)
The schema is represented as an array in the JSON data-interchange format. Each element of the array is a dimension objectwith other objects and arrays nested as shown in the following table:
Members or Elements TypesDescriptionTypeObject
DimensionThe JSON container for the schemaArrayTop level
DescriptionTypeNameDescribes onedimension andits children
ObjectDimension
The name of this dimensionstringname
The type of this dimensionstringtype
All the simple children ofthis dimension
array ofDimensionobjects
simpleChildren
All the countable childrenof this dimension
array ofDimensionobjects
countableChildren
All the manyToManychildren of this dimension
array ofDimensionobjects
manyToManyChildren
All the denormal childrenof this dimension
array ofDimensionobjects
denormalChildren
13Data Workbench Query API
![Page 14: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/14.jpg)
JSON Flattened Format (X-Format: json-flat)
This format is similar to the JSON format, except Dimension objects do not contain their children - all the Dimension objectsare contained directly in the top level array.
Members or Elements TypesDescriptionTypeObject
DimensionThe JSON container for the schemaArrayTop level
DescriptionTypeNameDescribes onedimension and itschildren
ObjectDimension
The name of this dimensionstringname
The type of this dimensionstringtype
Data Request Formats
The body of a Drop Request is empty.
The content of the response body for Create and Result Requests is shown below for the different formats.
Text Format (X-Format:text or Format=text)
Text formatted results consist of <TAB> separated, <CR><LF> terminated lines. The first line in this format is a header line,which contains data related to the complete request. This line is present in the response for both Create and Result requests. Itcontains two items, which are also available as response headers:
DescriptionResponse HeaderNameColumn
The unique ID assigned to this query when it was created.X-Query-IDQuery ID1
The completion level of this result, as a number in the range[0,1]. This is the minimum of the completion levels for allthe query statements in the request.
X-CompletionCompletion2
In the response to a Result or CreateWait request, following the heading line, the results for each query statement is given, inorder of the query statements.
The first line in of the result contains a single number, which is the number of result lines for this query statements (see exceptionbelow). The first item on each of the following lines is the name of the dimension elements. This is the only content of the linefor Dim Queries. For Metric Queries, the metric values for each metric are given, in the order listed in the query statement.
XML Format (X-Format:xml or Format=xml)
The result is represented hierarchically as XML. The following tags are used:
Child NodesAttributesDescriptionTag
One or more <DIM_QUERY>and/or <METRIC_QUERY > tags.
query_id - the unique ID assigned to thisquery when it was created.
The top level tag.<RESULT>
14Data Workbench Query API
![Page 15: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/15.jpg)
Child NodesAttributesDescriptionTag
completion - The completion level of thisresult, as a number in the range [0,1]. Thisis the minimum of the completion levelsfor all the query statements in the request.
The values of these attributes are identicalto those of the X-Query-ID andX-Completion response headers,respectively.
zero or more <ELEMENT> tagsdim - the name of the dimension.The results for a dimquery.
<DIM_QUERY>
dim - the name of the dimensionover which the query is evaluated.
dim - the name of the dimension overwhich the query is evaluated.
The results for ametric query.
<METRIC_QUE RY>
METRIC (only within aMETRIC_QUERY tag)
ordinal - the ordinal number (index) of thiselement.
Describes anelement of thedimension.
<ELEMENT>
name - the name of the element.
nonename - the metric's name.The value of a singlequery for theelement.
<METRIC>
value - the metric's value for this element.
JSON Format (X-Format:json or Format=json)
The data is represented as an array in the JSON data-interchange format.
The first element of the array is an object which contains data related to the complete request. It has two members, which arealso available as response headers:
DescriptionResponse HeaderMember
The unique ID assigned to this query when it was created.X-Query-IDqueryId
The completion level of this result, as a number in the range [0,1]. This isthe minimum of the completion levels for all the query statements in therequest.
X-Completioncompletion
Members or Element TypesDescriptionTypeMember
n/aThe query type.DimQuery orMetricQuery
type
n/aThe dimension being describedor over which the metrics arebeing evaluated.
stringdim
string - element nameDescribes one dimension andits children.
ARRAYelements
15Data Workbench Query API
![Page 16: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/16.jpg)
Members or Element TypesDescriptionTypeMember
DescriptionTypeNameThe results for a metric query(this element is omitted in dimqueries).
ARRAYmetrics
Each element of this array is theresult for one query statement,in the order they appear in therequest.
The name of thismetric.
stringname
The value of this metricfor each dimensionelement.
ARRAY ofstrings
values
Binary Format (X-Format:binary or Format=binary)
All numeric values are represented in Little Endian byte order.
Double values are represented as 8 byte floating-point numbers, using the IEEE REAL*8 format.
Int values are represented as 4 byte integers.
Int64 values are represented as 8 byte integers.
A string is represented as the string's 4-byte length (in bytes), followed by the characters, not NULLterminated. The strings arepassed through from the raw data, and their encoding is known to the system, but data workbench users are encouraged toprovide the data in the UTF-8 encoding.
The response body starts with a two element header:
double actualCompletionint64 Query-ID
Following the header, the results for each query statement is given, in the order of query statements in the query text.
Results of Dim Queries are represented as follows:
int nRowsint Cardinality
string name0
. . .
string namenRows-1
Results of Metric Queries are represented as follows:
int Cardinality
double valuenMetrics-1. . .double value0string name0
. . .
16Data Workbench Query API
![Page 17: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/17.jpg)
double valuenMetrics-1. . .double value0string namenRows-1
Where:
• Query-ID is the unique ID assigned to this query when it was created.• actualCompletion is the completion level of this result, as a number in the range [0,1]. This is the minimum of the completion
levels for all the query statements in the request.• Cardinality is the number of elements of the dimension.• nRows is the number of dimension elements that are listed in the result. It will be either the same as the cardinality, or, in rare
cases, when names are not available, 0.• namei is the name of the i-th dimension element.• valuej is the result for the j-th metric for the corresponding dimension element.• nMetrics is the number of metrics in the metric query.
Response Status Line
The following response status line are returned by the server:
MeaningMessageStatus Code
Success.OK200
The body of a Create Request was empty.Empty Query400
The X-Action header was missing.No Action400
The value of the X-Action header was not recognized.Unrecognized Action400
The X-Query-ID header was missing from a Result or Drop Request.No Query-ID400
The value of the X-Query-ID header did not refer to an existingquery, possibly because that query had timed out.
Query Not Found400
The deprecated X-Language header was used with an unrecognizedvalue. This header should no longer be used.
Unrecognized query language400
The Query Language Parser detected an error in the queryBad Query: (followed by parser errormessage)
400
The value of the X-Format header was not recognized.Bad Format Requested: (followed by value)400
The value of the X-Completion header was not valid.Bad X-Completion: (followed by value)400
An internal server error has occurred while calculating the resultsof the query. See X-Error Create Requests.
Query Error500
Server Configuration
By default, the data workbench server accepts API requests for each profile (at the URL described in The HTTP Protocol). Thisaccess is subject to access control, as described in the data workbench Dataset Configuration Guide.
17Data Workbench Query API
![Page 18: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/18.jpg)
To disable the API for a profile, the file server.cfg in the Dataset folder of that profile should contain the entry EnableQuery API with value set to false.
Sample Clients
Product releases include sample implementations of API clients.
HTML/Javascript Client
This sample client consists of three files:
• InsightAPI-Demo.html: A page containing a form with fields for the data workbench server name (or IP address), thename of the profile, and the query text.
• InsightAPI-Demo.js: Javascript source for this specific demo.• InsightAPI.js: A reusable set of Javascript classes for communicating with the data workbench server.
Perl Client
This sample client consists of three files:
• InsightAPI/Query.pm: A reusable module for communicating with the data workbench server.• example1.pl: A rudimentary demonstration of using the data InsightAPI::Query class.• example2.pl: A demonstration of different format outputs for schema and data queries.
Samples can be found on the Developer Connection site.
Contact and Legal Information
Information to help you contact Adobe and to understand the legal issues concerning your use of this product and documentation.
Help & Technical Support
The Adobe Marketing Cloud Customer Care team is here to assist you and provides a number of mechanisms by which theycan be engaged:
• Check the Marketing Cloud help pages for advice, tips, and FAQs• Ask us a quick question on Twitter @AdobeMktgCare• Log an incident in our customer portal• Contact the Customer Care team directly• Check availability and status of Marketing Cloud Solutions
Service, Capability & Billing
Dependent on your solution configuration, some options described in this documentation might not be available to you. Aseach account is unique, please refer to your contract for pricing, due dates, terms, and conditions. If you would like to add toor otherwise change your service level, or if you have questions regarding your current service, please contact your AccountManager.
Feedback
We welcome any suggestions or feedback regarding this solution. Enhancement ideas and suggestions for the Analytics suitecan be added to our Customer Idea Exchange.
18Data Workbench Query API
![Page 19: Dwb Query API](https://reader036.fdocuments.us/reader036/viewer/2022082505/563dbaa4550346aa9aa71a6b/html5/thumbnails/19.jpg)
Legal
© 2013, AdobeAll rights reserved.Published by Adobe Systems Inc.
Terms of Use | Privacy Center
A trademark symbol (®, ™, etc.) denotes an Adobe trademark.
All third-party trademarks are the property of their respective owners. Updated Information/Additional Third Party CodeInformation available at http://www.adobe.com/go/thirdparty.
06052013
19Data Workbench Query API