Platform Events Developer Guide
jNewer Version Available
ApiEvent
Tracks these user-initiated read-only API calls: query(), queryMore(),
and count(). Captures API requests through SOAP API,
REST API, and Bulk API for the Enterprise and Partner WSDLs. Tooling API calls and API
calls originating from a Salesforce mobile app aren’t captured. You can use ApiEvent
in a transaction security policy. ApiEvent is a big object that stores the event data of
ApiEventStream. This object is available in API version 46.0 and later.
Supported Calls
describeSObjects(), query()
Special Access Rules
Accessing this object requires either the Salesforce Shield or Salesforce Event Monitoring add-on subscription and the View Data Leakage Detection Events user permission.
Fields
Working With AdditionalInfo
AdditionalInfo enables you to extend the API event with custom data that can be queried later. For example, you can capture a correlation ID when a user executes a SOQL query from an external system that shares that unique ID. This process enables tracking API calls across systems. To store data with ApiEvent, begin all AdditionalInfo field names with x-sfdc-addinfo-{field name}. For example, a valid field assignment is x-sfdc-addinfo-correlation_id = ABC123 where x-sfdc-addinfo-correlation_id is the field name and ABC123 is the field value.
When defining field names, note the following:
- x-sfdc-addinfo- is case-insensitive; x-sfdc-addinfo-{field name} is the same as X-SFDC-ADDINFO-{field name} and x-SfDc-AdDiNfO-{field name}.
- Fields can contain only alphanumeric and "_" (underscore) characters.
- Field names must be from 2 through 29 characters in length, excluding x-sfdc-addinfo-.
- Field names that don’t start with x-sfdc-addinfo- are ignored.
- Names that contain invalid characters after x-sfdc-addinfo- are ignored, and nothing is stored. For example, a valid field name is x-sfdc-addinfo-correlation_id but x-sfdc-addinfo-correlation->id is not valid.
- Only the first 30 valid field names are stored in AdditionalInfo. If you store two valid field names—for example, x-sfdc-addinfo-correlation_id and x-sfdc-addinfo-correlation_number— you can store 28 additional field names. Field names are not necessarily stored in the same order in which they were passed to authentication.
- You can’t use existing API field names as AdditionalInfo names in the HTTP header. If the AdditionalInfo name conflicts with an object’s API name, the field value isn’t stored. For example, the HTTP header X-SFDC-ADDINFO-UserId='abc123' doesn’t get stored in AdditionalInfo.
- Additional field values can contain only alphanumeric, "_," and "-" characters.
- Field values must be 255 characters in length or fewer. If a field value exceeds 255 characters, only the first 255 characters are stored, and the rest are truncated.
- Field values that contain invalid characters are saved with a field header of Empty String ("").
- Only the first 30 valid field names are stored in the AdditionalInfo field. They are not guaranteed to be stored in the same order that they were passed into the authentication.
- When AggregationFieldName or PlatformEventMetrics is SourceIp, you can’t filter on AggregationFieldValue if its value is Salesforce.com IP.
How to Pass Additional Information by Using HTTP with cURL
1curl https://yourInstance.salesforce.com/services/data/v34.0/query?q=SELECT+Name+From+Account -H "X-PrettyPrint:1" -H "x-sfdc-addinfo-correlationid:
2d18c5a3f-4fba-47bd-bbf8-6bb9a1786624"Example of Using Java
1//adding additional info headers ..
2Map<String, String> httpHeaders = new HashMap<String,String>();
3httpHeaders.put("x-sfdc-addinfo-fieldname1" /* additional info field*/ , "d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
4httpHeaders.put("x-sfdc-addinfo-fieldname2" /* additional info field*/ , "d18c5a3f-4fba-47bd-bbf8-6bb9a1786624" /* value*/);
5
6ConnectorConfig config = new ConnectorConfig();
7config.setUsername(userId);
8config.setPassword(passwd);
9config.setAuthEndpoint(authEndPoint);
10config.setProxy(proxyHost, proxyPort);
11
12//setting additional info headers
13for (Map.Entry<String, String> entry : httpHeaders.entrySet()) {
14 config.setRequestHeader(entry.getKey(), entry.getValue());
15}
16// Set the username and password if your proxy must be authenticated
17 config.setProxyUsername(proxyUsername);
18 config.setProxyPassword(proxyPassword);
19 try {
20 QueryResult queryResult = connection.query("SELECT Id, Name FROM Account");
21 // etc.
22 } catch (ConnectionException ce) {
23 ce.printStackTrace();
24 }Standard SOQL Usage
ApiEvent allows filtering over two
fields: EventDate and EventIdentifier. The only
supported SOQL functions on the ApiEvent
object are WHERE, ORDER
BY, and LIMIT. In the WHERE clause, you can only use comparison operators (<,
>, <=, and >=). The != operator isn’t supported. In the ORDER BY clause, you can only use EventDate DESC. Ascending order isn’t supported with EventDate, and EventIdentifier
sorting isn’t supported.
The following list provides some examples of valid and invalid queries:
-
Unfiltered
-
Valid—Contains no WHERE
clause, so no special rules
apply.
1SELECT ApiType, Client, ElapsedTime, QueriedEntities, Username 2FROM ApiEvent
-
Valid—Contains no WHERE
clause, so no special rules
apply.
-
Filtered on EventDate—you can filter solely on EventDate, but single
filters on other fields fail. You can also use a comparison operator in this query type.
-
Valid—you can filter solely on EventDate, but
single filters on other fields fail. You can also use a comparison operator
in this query
type.
1SELECT ApiType, Client, ElapsedTime, QueriedEntities, Username 2FROM ApiEvent 3WHERE EventDate>=2014-11-27T14:54:16.000Z
-
Valid—you can filter solely on EventDate, but
single filters on other fields fail. You can also use a comparison operator
in this query
type.
Async SOQL Usage
With Async SOQL, you can filter on any field in ApiEvent and use any comparison operator in your query.
Example: Find all queries that users ran against Patent__c
SELECT EventDate, EventIdentifier, PolicyOutcome, EvaluationTime, Query FROM ApiEvent WHERE QueriedEntities='Patent_c'