Using gRPC

Introduction#

Some of Velocidi's API's are available through a gRPC interface. In particular, both the Event Storage and User Profile Storage modules provide gRPC interfaces, giving you access to the systems' captured user events and user attributes.

Available endpoints#

In order to access Velocidi's API's through gRPC you need to be aware of the available endpoints:

Modulesubdomainporte.g. endpoint
Event-Storageevents8888events.cdp.yourdomain.com:8888
User-Profile-Storageups8888ups.cdp.yourdomain.com:8888
Attributionattribution8888attribution.cdp.yourdomain.com:8888

These endpoints might not be open. If so, contact our support

Tooling#

To quickly experiment with the gRPC APIs from the Velocidi Private CDP the grpc_cli utility can be installed, which provides a terminal utility to call methods from any gRPC server.

In MacOS X this can be installed with:

brew tap grpc/grpc
brew install grpc

With this utility, one is fully capable of interacting with any standard gRPC server. For example, to list all the available services and methods on a given events.example.com endpoint: $ grpc_cli ls events.example.com:8888

$ grpc_cli ls events.example.com:8888
eu.shiftforward.adstax.events.api.grpc.service.EventStorage
grpc.reflection.v1alpha.ServerReflection
$ grpc_cli ls events.example.com:8888 eu.shiftforward.adstax.events.api.grpc.service.EventStorage
matchEventsSource
matchExtendedEventsSource
matchQuerySource
matchInsertSink
activationEventsSource
activationExtendedEventsSource
activationQuerySource
activationInsertSink
trackingEventsSource
trackingExtendedEventsSource
trackingQuerySource
trackingInsertSink

Below, we use the trackingEventsSource method to retrieve a list of user events within a given time range:

$ grpc_cli call events.example.com:8888 trackingEventsSource 'startTime: 1539693160981, endTime: 1539693174897'
call
events.example.com:8888
eu.shiftforward.adstax.events.api.grpc.service.EventStorage.trackingQuerySource
query: "SELECT * FROM TrackingEvents limit 1"
connecting to events.example.com:8888
columns {
struct_value {
fields {
key: "entity"
value {
null_value: NULL_VALUE
}
}
fields {
key: "headers"
value {
struct_value {
fields {
key: "Accept"
value {
string_value: "text/html, application/xhtml+xml, application/xml;q=0.9, */*;q=0.8"
}
}
fields {
key: "Accept-Charset"
value {
string_value: "ISO-8859-1, UTF-8;q=0.7, *;q=0.3"
}
}
...
...
...

Please refer to the EventStorage API documentation and UserProfileStorage API documentation to discover all the available services and methods.

AOQL event querying language in Event Storage#

Some of the gRPC methods provided by the Event Storage module accept a single string parameter named query. This parameter represents a query string in AOQL language. AOQL tries to abstract some of the differences between the storage infrastructure of different events types while providing a common set of operations that can be used to query all different events.

For example, here is the previous trackingEventsSource query now executed using an AOQL query string:

$ grpc_cli call events.example.com:8888 trackingQuerySource \
'query: "SELECT * FROM TrackingEvents where meta.timestamp >= 1539693160981 AND meta.timestamp < 1539693174897"'

Please refer to the AOQL documentation for details on its usage.

Last updated on