[Документация Yandex Cloud](../../../index.md) > [Yandex Audit Trails](../../index.md) > Справочник API > [REST (англ.)](../index.md) > [Trail](index.md) > Create # Audit Trails API, REST: Trail.Create Creates a trail in the specified folder. ## HTTP request ``` POST https://audittrails.api.yandexcloud.kz/audit-trails/v1/trails ``` ## Body parameters {#yandex.cloud.audittrails.v1.CreateTrailRequest} ```json { "folderId": "string", "name": "string", "description": "string", "labels": "object", "destination": { // Includes only one of the fields `objectStorage`, `cloudLogging`, `dataStream`, `eventrouter` "objectStorage": { "bucketId": "string", "objectPrefix": "string" }, "cloudLogging": { // Includes only one of the fields `logGroupId` "logGroupId": "string" // end of the list of possible fields }, "dataStream": { "databaseId": "string", "streamName": "string", "codec": "string" }, "eventrouter": { "eventrouterConnectorId": "string" } // end of the list of possible fields }, "serviceAccountId": "string", "filter": { "pathFilter": { "root": { // Includes only one of the fields `anyFilter`, `someFilter` "anyFilter": { "resource": { "id": "string", "type": "string" } }, "someFilter": { "resource": { "id": "string", "type": "string" }, "filters": [ "object" ] } // end of the list of possible fields } }, "eventFilter": { "filters": [ { "service": "string", "categories": [ { "plane": "string", "type": "string" } ], "pathFilter": { "root": { // Includes only one of the fields `anyFilter`, `someFilter` "anyFilter": { "resource": { "id": "string", "type": "string" } }, "someFilter": { "resource": { "id": "string", "type": "string" }, "filters": [ "object" ] } // end of the list of possible fields } } } ] } }, "filteringPolicy": { "managementEventsFilter": { "resourceScopes": [ { "id": "string", "type": "string" } ] }, "dataEventsFilters": [ { // Includes only one of the fields `includedEvents`, `excludedEvents` "includedEvents": { "eventTypes": [ "string" ] }, "excludedEvents": { "eventTypes": [ "string" ] }, // end of the list of possible fields // Includes only one of the fields `dnsFilter` "dnsFilter": { "includeNonrecursiveQueries": "boolean" }, // end of the list of possible fields "service": "string", "resourceScopes": [ { "id": "string", "type": "string" } ] } ] } } ``` #| ||Field | Description || || folderId | **string** Required field. ID of the folder to create a trail in. The maximum string length in characters is 50. || || name | **string** Name of the trail. Value must match the regular expression ` [a-z]([-a-z0-9]{0,61}[a-z0-9])? `. || || description | **string** Description of the trail. The maximum string length in characters is 1024. || || labels | **object** (map<**string**, **string**>) Custom labels for the secret as `key:value` pairs. Maximum 64 per key. For example, `"type": "critical"` or `"source": "dictionary"`. The maximum string length in characters for each value is 63. The maximum string length in characters for each key is 63. Each key must match the regular expression ` [a-z][-_0-9a-z]* `. Each value must match the regular expression ` [-_0-9a-z]* `. No more than 64 per resource. || || destination | **[Destination](#yandex.cloud.audittrails.v1.Trail.Destination)** Required field. Destination configuration for the trail || || serviceAccountId | **string** Required field. Service account ID of the trail The maximum string length in characters is 50. || || filter | **[Filter](#yandex.cloud.audittrails.v1.Trail.Filter)** Event filtering configuration of the trail deprecated: use filtering_policy instead || || filteringPolicy | **[FilteringPolicy](#yandex.cloud.audittrails.v1.Trail.FilteringPolicy)** Event filtering policy of the trail || |# ## Destination {#yandex.cloud.audittrails.v1.Trail.Destination} #| ||Field | Description || || objectStorage | **[ObjectStorage](#yandex.cloud.audittrails.v1.Trail.ObjectStorage)** Configuration for event delivery to Object Storage Uploaded objects will have prefix <trail_id>/ by default Includes only one of the fields `objectStorage`, `cloudLogging`, `dataStream`, `eventrouter`. || || cloudLogging | **[CloudLogging](#yandex.cloud.audittrails.v1.Trail.CloudLogging)** Configuration for event delivery to Cloud Logging Includes only one of the fields `objectStorage`, `cloudLogging`, `dataStream`, `eventrouter`. || || dataStream | **[DataStream](#yandex.cloud.audittrails.v1.Trail.DataStream)** Configuration for event delivery to YDS Includes only one of the fields `objectStorage`, `cloudLogging`, `dataStream`, `eventrouter`. || || eventrouter | **[EventRouter](#yandex.cloud.audittrails.v1.Trail.EventRouter)** Configuration for event delivery to EventRouter Includes only one of the fields `objectStorage`, `cloudLogging`, `dataStream`, `eventrouter`. || |# ## ObjectStorage {#yandex.cloud.audittrails.v1.Trail.ObjectStorage} #| ||Field | Description || || bucketId | **string** Name of the destination bucket The string length in characters must be 3-63. || || objectPrefix | **string** Prefix for exported objects. Optional If specified, uploaded objects will have prefix <object_prefix>/<trail_id>/ || |# ## CloudLogging {#yandex.cloud.audittrails.v1.Trail.CloudLogging} #| ||Field | Description || || logGroupId | **string** ID of the Cloud Logging destination group The maximum string length in characters is 64. Includes only one of the fields `logGroupId`. || |# ## DataStream {#yandex.cloud.audittrails.v1.Trail.DataStream} #| ||Field | Description || || databaseId | **string** ID of the database hosting the destination YDS || || streamName | **string** Name of the destination YDS || || codec | **enum** (Codec) Codec for compressing events - `RAW` - `GZIP` - `ZSTD` || |# ## EventRouter {#yandex.cloud.audittrails.v1.Trail.EventRouter} #| ||Field | Description || || eventrouterConnectorId | **string** ID of the EventRouter Connector The maximum string length in characters is 64. || |# ## Filter {#yandex.cloud.audittrails.v1.Trail.Filter} #| ||Field | Description || || pathFilter | **[PathFilter](#yandex.cloud.audittrails.v1.Trail.PathFilter)** Configuration of default events gathering for the trail If not specified, default events won't be gathered for the trail || || eventFilter | **[EventFilter](#yandex.cloud.audittrails.v1.Trail.EventFilter)** Configuration of additional events gathering from specific services || |# ## PathFilter {#yandex.cloud.audittrails.v1.Trail.PathFilter} #| ||Field | Description || || root | **[PathFilterElement](#yandex.cloud.audittrails.v1.Trail.PathFilterElement)** Required field. Root element of the resource path filter for the trail Resource described in that filter node must contain the trail itself || |# ## PathFilterElement {#yandex.cloud.audittrails.v1.Trail.PathFilterElement} #| ||Field | Description || || anyFilter | **[PathFilterElementAny](#yandex.cloud.audittrails.v1.Trail.PathFilterElementAny)** Filter element with ANY type. If used, configures the trail to gather any events from the resource Includes only one of the fields `anyFilter`, `someFilter`. || || someFilter | **[PathFilterElementSome](#yandex.cloud.audittrails.v1.Trail.PathFilterElementSome)** Filter element with SOME type. If used, configures the trail to gather some of the events from the resource Includes only one of the fields `anyFilter`, `someFilter`. || |# ## PathFilterElementAny {#yandex.cloud.audittrails.v1.Trail.PathFilterElementAny} #| ||Field | Description || || resource | **[Resource](#yandex.cloud.audittrails.v1.Trail.Resource)** Required field. Resource definition || |# ## Resource {#yandex.cloud.audittrails.v1.Trail.Resource} #| ||Field | Description || || id | **string** Required field. ID of the resource The maximum string length in characters is 64. || || type | **string** Required field. Type of the resource The maximum string length in characters is 50. || |# ## PathFilterElementSome {#yandex.cloud.audittrails.v1.Trail.PathFilterElementSome} #| ||Field | Description || || resource | **[Resource](#yandex.cloud.audittrails.v1.Trail.Resource)** Required field. Definition of the resource that contains nested resources || || filters[] | **[PathFilterElement](#yandex.cloud.audittrails.v1.Trail.PathFilterElement)** Filters for the resources contained in the parent resource The number of elements must be greater than 0. || |# ## EventFilter {#yandex.cloud.audittrails.v1.Trail.EventFilter} #| ||Field | Description || || filters[] | **[EventFilterElement](#yandex.cloud.audittrails.v1.Trail.EventFilterElement)** List of filters for services The minimum number of elements is 0. || |# ## EventFilterElement {#yandex.cloud.audittrails.v1.Trail.EventFilterElement} #| ||Field | Description || || service | **string** Required field. Service ID of the gathered events || || categories[] | **[EventFilterElementCategory](#yandex.cloud.audittrails.v1.Trail.EventFilterElementCategory)** List of the event categories gathered for a specified service The number of elements must be greater than 0. || || pathFilter | **[PathFilter](#yandex.cloud.audittrails.v1.Trail.PathFilter)** Required field. Resource path filter for a specified service || |# ## EventFilterElementCategory {#yandex.cloud.audittrails.v1.Trail.EventFilterElementCategory} #| ||Field | Description || || plane | **enum** (EventCategoryFilter) Required field. Plane of the gathered category - `CONTROL_PLANE`: The events that are generated during the interaction with the service's resources - `DATA_PLANE`: Events that are generated during interaction with data within the service's resources || || type | **enum** (EventAccessTypeFilter) Required field. Type of the gathered category - `WRITE`: Events for operations that do perform some modification - `READ`: Events for operations that do not perform any modifications || |# ## FilteringPolicy {#yandex.cloud.audittrails.v1.Trail.FilteringPolicy} Combination of policies describing event filtering process of the trail At least one filed must be filled #| ||Field | Description || || managementEventsFilter | **[ManagementEventsFiltering](#yandex.cloud.audittrails.v1.Trail.ManagementEventsFiltering)** Singular filter describing gathering management events || || dataEventsFilters[] | **[DataEventsFiltering](#yandex.cloud.audittrails.v1.Trail.DataEventsFiltering)** List of filters describing gathering data events The number of elements must be less than 128. || |# ## ManagementEventsFiltering {#yandex.cloud.audittrails.v1.Trail.ManagementEventsFiltering} Policy for gathering management events #| ||Field | Description || || resourceScopes[] | **[Resource](#yandex.cloud.audittrails.v1.Trail.Resource)** A list of resources which will be monitored by the trail The number of elements must be in the range 1-1024. || |# ## DataEventsFiltering {#yandex.cloud.audittrails.v1.Trail.DataEventsFiltering} Policy for gathering data events #| ||Field | Description || || includedEvents | **[EventTypes](#yandex.cloud.audittrails.v1.Trail.EventTypes)** Explicitly included events of specified service New events of the service won't be delivered by default Includes only one of the fields `includedEvents`, `excludedEvents`. || || excludedEvents | **[EventTypes](#yandex.cloud.audittrails.v1.Trail.EventTypes)** Explicitly excluded events of specified service New events of the service will be delivered by default Includes only one of the fields `includedEvents`, `excludedEvents`. || || dnsFilter | **[DnsDataEventsFilter](#yandex.cloud.audittrails.v1.Trail.DnsDataEventsFilter)** Filter is allowed only if service = dns Includes only one of the fields `dnsFilter`. || || service | **string** Required field. Name of the service whose events will be delivered || || resourceScopes[] | **[Resource](#yandex.cloud.audittrails.v1.Trail.Resource)** A list of resources which will be monitored by the trail The number of elements must be in the range 1-1024. || |# ## EventTypes {#yandex.cloud.audittrails.v1.Trail.EventTypes} Policy with explicitly specified event group #| ||Field | Description || || eventTypes[] | **string** The number of elements must be in the range 1-1024. || |# ## DnsDataEventsFilter {#yandex.cloud.audittrails.v1.Trail.DnsDataEventsFilter} #| ||Field | Description || || includeNonrecursiveQueries | **boolean** Not only recursive queries will be delivered || |# ## Response {#yandex.cloud.operation.Operation} **HTTP Code: 200 - OK** ```json { "id": "string", "description": "string", "createdAt": "string", "createdBy": "string", "modifiedAt": "string", "done": "boolean", "metadata": "object", // Includes only one of the fields `error`, `response` "error": { "code": "integer", "message": "string", "details": [ "object" ] }, "response": "object" // end of the list of possible fields } ``` An Operation resource. For more information, see [Operation](../../../api-design-guide/concepts/operation.md). #| ||Field | Description || || id | **string** ID of the operation. || || description | **string** Description of the operation. 0-256 characters long. || || createdAt | **string** (date-time) Creation timestamp. String in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the [Protocol Buffers reference](https://developers.google.com/protocol-buffers/docs/reference/overview). In some languages, built-in datetime utilities do not support nanosecond precision (9 digits). || || createdBy | **string** ID of the user or service account who initiated the operation. || || modifiedAt | **string** (date-time) The time when the Operation resource was last modified. String in [RFC3339](https://www.ietf.org/rfc/rfc3339.txt) text format. The range of possible values is from `0001-01-01T00:00:00Z` to `9999-12-31T23:59:59.999999999Z`, i.e. from 0 to 9 digits for fractions of a second. To work with values in this field, use the APIs described in the [Protocol Buffers reference](https://developers.google.com/protocol-buffers/docs/reference/overview). In some languages, built-in datetime utilities do not support nanosecond precision (9 digits). || || done | **boolean** If the value is `false`, it means the operation is still in progress. If `true`, the operation is completed, and either `error` or `response` is available. || || metadata | **object** Service-specific metadata associated with the operation. It typically contains the ID of the target resource that the operation is performed on. Any method that returns a long-running operation should document the metadata type, if any. || || error | **[Status](#google.rpc.Status)** The error result of the operation in case of failure or cancellation. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set. || || response | **object** The normal response of the operation in case of success. If the original method returns no data on success, such as Delete, the response is [google.protobuf.Empty](https://developers.google.com/protocol-buffers/docs/reference/google.protobuf#google.protobuf.Empty). If the original method is the standard Create/Update, the response should be the target resource of the operation. Any method that returns a long-running operation should document the response type, if any. Includes only one of the fields `error`, `response`. The operation result. If `done == false` and there was no failure detected, neither `error` nor `response` is set. If `done == false` and there was a failure detected, `error` is set. If `done == true`, exactly one of `error` or `response` is set. || |# ## Status {#google.rpc.Status} The error result of the operation in case of failure or cancellation. #| ||Field | Description || || code | **integer** (int32) Error code. An enum value of [google.rpc.Code](https://github.com/googleapis/googleapis/blob/master/google/rpc/code.proto). || || message | **string** An error message. || || details[] | **object** A list of messages that carry the error details. || |#