BatchCreateUDMEvents to ImportEvents APIs request and response mapping

Supported in:

Google secops SIEM

This guide details the request and response mapping specifications and property parity analysis for migrating from the legacy Ingestion API v2 (BatchCreateUDMEvents) to the modern Chronicle API (ImportEvents).

[!IMPORTANT] The modern ImportEvents API does not accept legacy Ingestion API keys or partner tokens. Callers must authenticate using standard Google Cloud IAM credentials authorized with chronicle.googleapis.com/events.import for the target instance resource.

Protocol and mapping overview

Feature	Legacy API v2 (`BatchCreateUDMEvents`)	Modern Chronicle API (`ImportEvents`)
HTTP method	`POST`	`POST`
Permissions	Ingestion API key or legacy partner tokens	`chronicle.googleapis.com/events.import`

Request payload field-by-field parity

In the legacy Ingestion API v2, callers submitted Unified Data Model (UDM) event batches using BatchCreateUDMEventsRequest, specifying customer_id and an optional log_type or associated raw log entries in the request body.

In the modern Chronicle API, events are ingested through ImportEventsRequest. The request scopes the target customer instance using the parent URL path parameter and wraps the event batch inside an inline_source structure (EventsInlineSource), with each event structured as an Event resource container.

Legacy field (`BatchCreateUDMEventsRequest`)	Modern field (`ImportEventsRequest`)	Field type	Parity and migration notes
`customer_id`	`parent` (in HTTP path)	`string`	Google Cloud scoping hierarchy: In legacy v2, the customer GUID was supplied in `customer_id`. In the modern API, the customer instance is specified directly in the request URL: `projects/{project}/locations/{location}/instances/{instance}`.
—	`inline_source`	`EventsInlineSource` (oneof `source`)	Encapsulation wrapper: Modern Chronicle API encapsulates inline event batches inside a `oneof source` container (`inline_source`).
`events`	`inline_source.events`	`repeated Event`	Parity mapped with resource container: Repeated list of UDM events to be ingested. Whereas legacy v2 held `repeated backstory.UDM` directly, the modern API encapsulates each event in a canonical `Event` resource container holding the `udm` payload and an optional `name` identifier.
`log_type`	`inline_source.events[].udm.metadata.product_name`	`string`	Embedded in UDM metadata: In legacy v2, an optional top-level `log_type` could be specified (defaulting to `UDM`). In the modern API, event categorization and product identification are modeled directly inside each event's UDM metadata (`udm.metadata.vendor_name`, `udm.metadata.product_name`, and `udm.metadata.product_event_type`).
`entries`	—	`repeated UnstructuredLogEntry`	Decoupled raw log ingestion: In legacy v2, callers could optionally attach raw unparsed log strings alongside UDM events. In modern Chronicle architecture, raw log ingestion is handled through `ImportLogs` to ensure proper pipeline indexing and normalization, while `ImportEvents` is dedicated strictly to structured UDM telemetry.

Event container and UDM structure parity (`backstory.UDM` versus `google.cloud.chronicle.v1main.Event`)

Each item in inline_source.events is an Event resource container whose internal udm field retains 100% schema fidelity with the Universal Data Model (backstory.UDM):

Modern field (`Event`)	Legacy equivalent	Field type	Parity and migration notes
`name`	—	`string`	New field: Optional canonical resource name of the event (`projects/{project}/locations/{location}/instances/{instance}/events/{event_id}` where `{event_id}` is the URL-encoded Base64 representation of `udm.metadata.id`).
`udm`	`events[]`	`backstory.UDM`	Direct mapping: Complete UDM event payload containing event taxonomy, entities, network attributes, and metadata.

Top-level UDM event fields (`backstory.UDM`)

The schema of udm inside each Event directly corresponds to the legacy UDM event structure:

UDM field	Field type	Parity and migration notes
`metadata`	`Metadata`	Direct mapping: Core event metadata including `event_timestamp`, `event_type`, `product_name`, `vendor_name`, `product_event_type`, `product_log_id`, and `id`.
`principal`	`Noun`	Direct mapping: Acting entity (user, asset, process) originating the activity.
`target`	`Noun`	Direct mapping: Target entity (user, asset, file, process, registry) being acted upon.
`src`	`Noun`	Direct mapping: Source entity where activity originated when distinct from `principal`.
`intermediary`	`repeated Noun`	Direct mapping: Proxy servers, firewalls, or relay devices through which the activity passed.
`observer`	`Noun`	Direct mapping: Sensors, packet sniffers, or scanning engines that observed the activity.
`about`	`repeated Noun`	Direct mapping: Ancillary entities referenced in the event (such as file attachments or embedded URLs).
`security_result`	`repeated SecurityResult`	Direct mapping: Security verdicts, detection actions, alert classifications, and risk scores.
`network`	`Network`	Direct mapping: Network protocol metadata, including `ip_protocol`, `direction`, and protocol-specific details (such as HTTP, DNS, DHCP, email).
`extensions`	`Extensions`	Direct mapping: Domain-specific telemetry extensions (such as authentication, vulnerability, or cloud context).
`additional`	`google.protobuf.Struct`	Direct mapping: Dynamic JSON structure for supplementary vendor attributes not accommodated in standard UDM fields.
`extracted`	`google.protobuf.Struct`	Direct mapping: Raw log fields extracted during processing.
`grouped`	`GroupedFields`	Direct mapping: Grouped fields for correlated telemetry attributes.

Response payload field-by-field parity

Both endpoints return an empty confirmation payload upon successful receipt and queuing of the event batch.

Legacy field (`BatchCreateUDMEventsResponse`)	Modern field (`ImportEventsResponse`)	Field type	Parity and migration notes
—	—	`message`	Equivalent: Both APIs return an empty JSON object (`{}`) upon successful validation of the event batch.

Key differences

Resource-scoped URL vs. global endpoint:
- Legacy BatchCreateUDMEvents sent requests to a global endpoint (/v2/udmevents:batchCreate), passing customer_id in the request body.
- Modern ImportEvents adopts Google Cloud resource hierarchy standards, placing instance ownership directly in the URL path (/v1/projects/{project}/locations/{location}/instances/{instance}/events:import).
Payload encapsulation (oneof source):
- Legacy v2 accepted the events array directly at the root level of the request body.
- Modern ImportEvents wraps the event batch inside an inline_source container (EventsInlineSource), preparing the contract for future ingestion sources while encapsulating each UDM payload in an Event resource wrapper.
Separation of raw unparsed logs from UDM events:
- Legacy v2 included an optional entries field allowing raw log strings to accompany UDM events.
- Modern Chronicle architecture cleanly distinguishes between raw log ingestion (ImportLogs), which triggers Chronicle parsing pipelines, and pre-normalized UDM ingestion (ImportEvents), which inserts structured telemetry directly into the UDM data plane.
Atomic batch validation consistency:
- Both legacy v2 and modern APIs enforce atomic validation across the entire batch: all events in the request must be valid for the call to succeed. A validation error in any single event causes the entire import request to fail.
Modern IAM authorization:
- Authentication transitions from legacy Ingestion API keys to standard Google Cloud IAM credentials with the chronicle.googleapis.com/events.import permission.