Event Group Metadata Descriptors API

​

Resource

​

EventGroupMetadataDescriptor

​

Methods

​

GetEventGroupMetadataDescriptor

message GetEventGroupMetadataDescriptorRequest {
  string name = 1 [(google.api.field_behavior) = REQUIRED];
}

GET /v2alpha/{name=dataProviders/*/eventGroupMetadataDescriptors/*}

​

CreateEventGroupMetadataDescriptor

message CreateEventGroupMetadataDescriptorRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  EventGroupMetadataDescriptor event_group_metadata_descriptor = 2 [(google.api.field_behavior) = REQUIRED];
  string request_id = 3;
}

• The descriptor_set should include the complete type definition including all dependencies.
• The request_id should ideally be the protobuf type URL for consistency.
• The descriptor set enables self-describing metadata without compile-time dependencies.

​

UpdateEventGroupMetadataDescriptor

message UpdateEventGroupMetadataDescriptorRequest {
  EventGroupMetadataDescriptor event_group_metadata_descriptor = 1 [(google.api.field_behavior) = REQUIRED];
}

• This performs a full replacement update.
• Partial updates are not supported.
• The name field identifies which descriptor to update.
• Use this to update the descriptor set when your metadata schema changes.

​

BatchGetEventGroupMetadataDescriptors

message BatchGetEventGroupMetadataDescriptorsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  repeated string names = 2 [(google.api.field_behavior) = REQUIRED];
}

message BatchGetEventGroupMetadataDescriptorsResponse {
  repeated EventGroupMetadataDescriptor event_group_metadata_descriptors = 1;
}

GET /v2alpha/{parent=dataProviders/*}/eventGroupMetadataDescriptors:batchGet

​

ListEventGroupMetadataDescriptors

message ListEventGroupMetadataDescriptorsRequest {
  string parent = 1 [(google.api.field_behavior) = REQUIRED];
  int32 page_size = 2;
  string page_token = 3;
}

message ListEventGroupMetadataDescriptorsResponse {
  repeated EventGroupMetadataDescriptor event_group_metadata_descriptors = 1;
  string next_page_token = 2;
}

​

Self-Describing Metadata

​

Concept

​

FileDescriptorSet

1. Message Descriptor: The FileDescriptorProto containing your metadata message definition
2. Dependencies: All transitive dependencies of your message
3. Exclusions: Well-known types may be excluded as they’re universally available

​

Creating a Descriptor Set

# Compile your .proto file with descriptor_set_out
protoc --descriptor_set_out=metadata_descriptor.pb \
       --include_imports \
       your_metadata.proto

​

Using Descriptors

1. Fetch the EventGroupMetadataDescriptor
2. Extract the descriptor_set
3. Use reflection APIs to parse and understand the metadata
4. No compile-time dependency on the metadata schema required

​

Workflow

​

Defining Metadata Schema

1. Design Schema: Create a .proto file defining your metadata structure:

syntax = "proto3";

package com.example.metadata;

message CampaignMetadata {
  string campaign_id = 1;
  string campaign_name = 2;
  string advertiser = 3;
  repeated string creative_ids = 4;
}

2. Generate Descriptor: Compile with --descriptor_set_out:

protoc --descriptor_set_out=campaign_metadata.pb \
       --include_imports \
       campaign_metadata.proto

3. Load Descriptor: Read the generated .pb file into a FileDescriptorSet.
4. Create Descriptor Resource: Call CreateEventGroupMetadataDescriptor with the descriptor set.

​

Registering Descriptors

1. One Per Schema: Create one descriptor per unique metadata schema.
2. Use Type URL as Request ID: The protobuf type URL (e.g., type.googleapis.com/com.example.metadata.CampaignMetadata) makes a good request_id.
3. Store Reference: Save the returned resource name for use in EventGroups.

​

Using Descriptors with EventGroups

1. Reference Descriptor: Set event_group_metadata_descriptor to the descriptor resource name.
2. Provide Metadata: Include the actual metadata message in the metadata field.
3. Type Matching: The metadata must match the type defined in the descriptor.

​

Updating Schemas

1. Version Control: Maintain backward compatibility when updating schemas.
2. Create New Descriptor: For breaking changes, create a new descriptor instead of updating.
3. Update Descriptor: For compatible changes, update the existing descriptor.
4. Migrate EventGroups: Update EventGroups to reference the new descriptor.

​

Best Practices

​

Schema Design

• Backward Compatibility: Use field numbers that won’t conflict with future additions.
• Optional Fields: Make fields optional when possible for flexibility.
• Documentation: Include comments in your .proto files.
• Namespacing: Use package names to avoid type collisions.

​

Descriptor Management

• Versioning: Include version information in your schema if needed.
• Dependencies: Minimize external dependencies for simpler descriptor sets.
• Well-Known Types: Leverage protobuf well-known types (they can be excluded from the descriptor set).
• Testing: Validate descriptor sets can be deserialized correctly.

​

Cross-Provider Compatibility

• Standard Schemas: Consider using common schemas across DataProviders.
• List Across Providers: Use dataProviders/- to discover all available descriptors.
• Batch Operations: Use batch get for efficient retrieval of multiple descriptors.
• Caching: Cache descriptors as they rarely change.

​

Error Handling

• Validation: Validate descriptor sets before creating resources.
• Idempotency: Use request_id to make creation idempotent.
• Type Checking: Ensure EventGroup metadata matches the referenced descriptor.
• Not Found: Handle cases where descriptors may have been deleted.

​

Integration Examples

​

Creating a Descriptor and EventGroup

// 1. Create the descriptor
CreateEventGroupMetadataDescriptorRequest {
  parent: "dataProviders/123"
  event_group_metadata_descriptor: {
    descriptor_set: <loaded from campaign_metadata.pb>
  }
  request_id: "type.googleapis.com/com.example.metadata.CampaignMetadata"
}

// Response includes name: "dataProviders/123/eventGroupMetadataDescriptors/456"

// 2. Create EventGroup referencing the descriptor
CreateEventGroupRequest {
  parent: "dataProviders/123"
  event_group: {
    measurement_consumer: "measurementConsumers/789"
    encrypted_metadata: {
      metadata: {
        event_group_metadata_descriptor: "dataProviders/123/eventGroupMetadataDescriptors/456"
        metadata: <packed CampaignMetadata message>
      }
    }
    // ... other fields
  }
}

​

Discovering and Using Descriptors

// 1. List all descriptors across providers
ListEventGroupMetadataDescriptorsRequest {
  parent: "dataProviders/-"
}

// 2. Get specific descriptors
BatchGetEventGroupMetadataDescriptorsRequest {
  parent: "dataProviders/123"
  names: [
    "dataProviders/123/eventGroupMetadataDescriptors/456",
    "dataProviders/123/eventGroupMetadataDescriptors/789"
  ]
}

// 3. Use reflection to parse metadata
// Load descriptor set
// Create dynamic message from descriptor
// Parse metadata from EventGroup