From 3a0a7f34641d69e63a334bf03829ae3bda8fe49d Mon Sep 17 00:00:00 2001 From: Lisa Cawley Date: Sat, 4 Jan 2025 00:13:54 -0800 Subject: [PATCH] Add specification for post event to an analytics collection (#3363) Co-authored-by: Laura Trotta <153528055+l-trotta@users.noreply.github.com> Co-authored-by: Quentin Pradet (cherry picked from commit 2f57f6bbe10648cf0b45a8b7ed6ea37cbecf1494) --- .../elasticsearch-openapi-overlays.yaml | 10 ++ output/openapi/elasticsearch-openapi.json | 88 ++++++++++ output/schema/schema-serverless.json | 22 +++ output/schema/schema.json | 165 +++++++++++++++++- output/schema/validation-errors.json | 6 - output/typescript/types.ts | 14 ++ specification/_doc_ids/table.csv | 2 + .../BehavioralAnalyticsEventPostRequest.ts | 51 ++++++ ...oralAnalyticsEventPostRequestExample1.yaml | 13 ++ .../BehavioralAnalyticsEventPostResponse.ts | 47 +++++ 10 files changed, 408 insertions(+), 10 deletions(-) create mode 100644 specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequest.ts create mode 100644 specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequestExample1.yaml create mode 100644 specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostResponse.ts diff --git a/docs/overlays/elasticsearch-openapi-overlays.yaml b/docs/overlays/elasticsearch-openapi-overlays.yaml index dd877b2a8c..712c9747ca 100644 --- a/docs/overlays/elasticsearch-openapi-overlays.yaml +++ b/docs/overlays/elasticsearch-openapi-overlays.yaml @@ -392,6 +392,16 @@ actions: examples: indicesLegacyPutTemplateRequestExample1: $ref: "../../specification/indices/put_template/indicesPutTemplateRequestExample1.yaml" +## Examples for behavioral analytics + - target: "$.paths['/_application/analytics/{collection_name}/event/{event_type}']['post']" + description: "Add examples for post analytics collection event operation" + update: + requestBody: + content: + application/json: + examples: + postBehavioralAnalyticsEventRequestExample1: + $ref: "../../specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequestExample1.yaml" ## Examples for licensing - target: "$.paths['/_license/basic_status']['get']" description: "Add example for get basic status response" diff --git a/output/openapi/elasticsearch-openapi.json b/output/openapi/elasticsearch-openapi.json index 53f0ea988b..6ea81a8344 100644 --- a/output/openapi/elasticsearch-openapi.json +++ b/output/openapi/elasticsearch-openapi.json @@ -27191,6 +27191,86 @@ "x-beta": true } }, + "/_application/analytics/{collection_name}/event/{event_type}": { + "post": { + "tags": [ + "analytics" + ], + "summary": "Create a behavioral analytics collection event", + "externalDocs": { + "url": "https://www.elastic.co/guide/en/elasticsearch/reference/current/behavioral-analytics-event-reference.html" + }, + "operationId": "search-application-post-behavioral-analytics-event", + "parameters": [ + { + "in": "path", + "name": "collection_name", + "description": "The name of the behavioral analytics collection.", + "required": true, + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/_types:Name" + }, + "style": "simple" + }, + { + "in": "path", + "name": "event_type", + "description": "The analytics event type.", + "required": true, + "deprecated": false, + "schema": { + "$ref": "#/components/schemas/search_application._types:EventType" + }, + "style": "simple" + }, + { + "in": "query", + "name": "debug", + "description": "Whether the response type has to include more details", + "deprecated": false, + "schema": { + "type": "boolean" + }, + "style": "form" + } + ], + "requestBody": { + "content": { + "application/json": { + "schema": { + "type": "object" + } + } + }, + "required": true + }, + "responses": { + "200": { + "description": "", + "content": { + "application/json": { + "schema": { + "type": "object", + "properties": { + "accepted": { + "type": "boolean" + }, + "event": { + "type": "object" + } + }, + "required": [ + "accepted" + ] + } + } + } + } + }, + "x-state": "Technical preview" + } + }, "/_application/search_application/{name}/_render_query": { "post": { "tags": [ @@ -83228,6 +83308,14 @@ "updated_at_millis" ] }, + "search_application._types:EventType": { + "type": "string", + "enum": [ + "page_view", + "search", + "search_click" + ] + }, "search_application.put_behavioral_analytics:AnalyticsAcknowledgeResponseBase": { "allOf": [ { diff --git a/output/schema/schema-serverless.json b/output/schema/schema-serverless.json index fa8f0ff0d6..89e021f8d9 100644 --- a/output/schema/schema-serverless.json +++ b/output/schema/schema-serverless.json @@ -103347,6 +103347,28 @@ }, "specLocation": "rollup/get_jobs/types.ts#L66-L72" }, + { + "kind": "enum", + "members": [ + { + "codegenName": "PageView", + "name": "page_view" + }, + { + "codegenName": "Search", + "name": "search" + }, + { + "codegenName": "SearchClick", + "name": "search_click" + } + ], + "name": { + "name": "EventType", + "namespace": "search_application._types" + }, + "specLocation": "search_application/_types/AnalyticsEvent.ts#L22-L26" + }, { "kind": "enum", "members": [ diff --git a/output/schema/schema.json b/output/schema/schema.json index 71886bb50d..852560c401 100644 --- a/output/schema/schema.json +++ b/output/schema/schema.json @@ -14936,15 +14936,25 @@ "visibility": "public" } }, - "description": "Creates a behavioral analytics event for existing collection.", - "docUrl": "http://todo.com/tbd", + "description": "Create a behavioral analytics collection event.", + "docId": "behavioral-analytics-collection-event", + "docTag": "analytics", + "docUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/post-analytics-collection-event.html", + "extDocId": "behavioral-analytics-event-reference", + "extDocUrl": "https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/behavioral-analytics-event-reference.html", "name": "search_application.post_behavioral_analytics_event", - "request": null, + "request": { + "name": "Request", + "namespace": "search_application.post_behavioral_analytics_event" + }, "requestBodyRequired": true, "requestMediaType": [ "application/json" ], - "response": null, + "response": { + "name": "Response", + "namespace": "search_application.post_behavioral_analytics_event" + }, "responseMediaType": [ "application/json" ], @@ -188144,6 +188154,28 @@ ], "specLocation": "search_application/_types/BehavioralAnalytics.ts#L29-L31" }, + { + "kind": "enum", + "members": [ + { + "codegenName": "PageView", + "name": "page_view" + }, + { + "codegenName": "Search", + "name": "search" + }, + { + "codegenName": "SearchClick", + "name": "search_click" + } + ], + "name": { + "name": "EventType", + "namespace": "search_application._types" + }, + "specLocation": "search_application/_types/AnalyticsEvent.ts#L22-L26" + }, { "kind": "interface", "name": { @@ -188647,6 +188679,131 @@ ], "specLocation": "search_application/list/SearchApplicationsListResponse.ts#L31-L48" }, + { + "kind": "request", + "attachedBehaviors": [ + "CommonQueryParameters" + ], + "body": { + "kind": "value", + "codegenName": "payload", + "value": { + "kind": "user_defined_value" + } + }, + "description": "Create a behavioral analytics collection event.", + "inherits": { + "type": { + "name": "RequestBase", + "namespace": "_types" + } + }, + "name": { + "name": "Request", + "namespace": "search_application.post_behavioral_analytics_event" + }, + "path": [ + { + "description": "The name of the behavioral analytics collection.", + "name": "collection_name", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "Name", + "namespace": "_types" + } + } + }, + { + "description": "The analytics event type.", + "name": "event_type", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "EventType", + "namespace": "search_application._types" + } + } + } + ], + "query": [ + { + "description": "Whether the response type has to include more details", + "name": "debug", + "required": false, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + } + ], + "specLocation": "search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequest.ts#L24-L51" + }, + { + "kind": "response", + "body": { + "kind": "properties", + "properties": [ + { + "name": "accepted", + "required": true, + "type": { + "kind": "instance_of", + "type": { + "name": "boolean", + "namespace": "_builtins" + } + } + }, + { + "name": "event", + "required": false, + "type": { + "kind": "user_defined_value" + } + } + ] + }, + "exceptions": [ + { + "body": { + "kind": "no_body" + }, + "description": "\nEvent has been accepted and will be ingested.", + "statusCodes": [ + 202 + ] + }, + { + "body": { + "kind": "no_body" + }, + "description": "\nEither the event type is unknown or the event payload contains invalid data.", + "statusCodes": [ + 400 + ] + }, + { + "body": { + "kind": "no_body" + }, + "description": "\nAnalytics collection does not exist.", + "statusCodes": [ + 404 + ] + } + ], + "name": { + "name": "Response", + "namespace": "search_application.post_behavioral_analytics_event" + }, + "specLocation": "search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostResponse.ts#L22-L47" + }, { "kind": "request", "attachedBehaviors": [ diff --git a/output/schema/validation-errors.json b/output/schema/validation-errors.json index 1efde6f560..fd2da7f050 100644 --- a/output/schema/validation-errors.json +++ b/output/schema/validation-errors.json @@ -908,12 +908,6 @@ ], "response": [] }, - "search_application.post_behavioral_analytics_event": { - "request": [ - "Missing request & response" - ], - "response": [] - }, "search_mvt": { "request": [ "Request: query parameter 'grid_agg' does not exist in the json spec", diff --git a/output/typescript/types.ts b/output/typescript/types.ts index 86bd6837e8..d6feaff274 100644 --- a/output/typescript/types.ts +++ b/output/typescript/types.ts @@ -17659,6 +17659,8 @@ export interface SearchApplicationEventDataStream { name: IndexName } +export type SearchApplicationEventType = 'page_view' | 'search' | 'search_click' + export interface SearchApplicationSearchApplication { name: Name indices: IndexName[] @@ -17713,6 +17715,18 @@ export interface SearchApplicationListSearchApplicationListItem { analytics_collection_name?: Name } +export interface SearchApplicationPostBehavioralAnalyticsEventRequest extends RequestBase { + collection_name: Name + event_type: SearchApplicationEventType + debug?: boolean + body?: any +} + +export interface SearchApplicationPostBehavioralAnalyticsEventResponse { + accepted: boolean + event?: any +} + export interface SearchApplicationPutRequest extends RequestBase { name: Name create?: boolean diff --git a/specification/_doc_ids/table.csv b/specification/_doc_ids/table.csv index 28ec7b722c..90ace064ef 100644 --- a/specification/_doc_ids/table.csv +++ b/specification/_doc_ids/table.csv @@ -18,6 +18,8 @@ autoscaling-get-autoscaling-capacity,https://www.elastic.co/guide/en/elasticsear autoscaling-get-autoscaling-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-get-autoscaling-policy.html autoscaling-put-autoscaling-policy,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/autoscaling-put-autoscaling-policy.html avoid-index-pattern-collisions,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/index-templates.html#avoid-index-pattern-collisions +behavioral-analytics-collection-event,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/post-analytics-collection-event.html +behavioral-analytics-event-reference,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/behavioral-analytics-event-reference.html byte-units,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/api-conventions.html#byte-units bytes-processor,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/bytes-processor.html calendar-and-fixed-intervals,https://www.elastic.co/guide/en/elasticsearch/reference/{branch}/search-aggregations-bucket-datehistogram-aggregation.html#calendar_and_fixed_intervals diff --git a/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequest.ts b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequest.ts new file mode 100644 index 0000000000..a6d7c64bf4 --- /dev/null +++ b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequest.ts @@ -0,0 +1,51 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ +import { UserDefinedValue } from '@spec_utils/UserDefinedValue' +import { RequestBase } from '@_types/Base' +import { Name } from '@_types/common' +import { EventType } from '../_types/AnalyticsEvent' + +/** + * Create a behavioral analytics collection event. + * @rest_spec_name search_application.post_behavioral_analytics_event + * @availability stack stability=experimental visibility=public + * @doc_tag analytics + * @doc_id behavioral-analytics-collection-event + * @ext_doc_id behavioral-analytics-event-reference + */ +export interface Request extends RequestBase { + path_parts: { + /** + * The name of the behavioral analytics collection. + */ + collection_name: Name + /** + * The analytics event type. + */ + event_type: EventType + } + query_parameters: { + /** + * Whether the response type has to include more details + */ + debug?: boolean + } + /** @codegen_name payload */ + body: UserDefinedValue +} diff --git a/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequestExample1.yaml b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequestExample1.yaml new file mode 100644 index 0000000000..d52bfbdd3d --- /dev/null +++ b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostRequestExample1.yaml @@ -0,0 +1,13 @@ +# summary: behavioral-analytics/apis/post-analytics-collection-event.asciidoc:69 +# method_request: POST _application/analytics/my_analytics_collection/event/search_click +description: Run `POST _application/analytics/my_analytics_collection/event/search_click` to send a `search_click` event to an analytics collection called `my_analytics_collection`. +# type: request +value: + "{\n \"session\": {\n \"id\": \"1797ca95-91c9-4e2e-b1bd-9c38e6f386a9\"\n\ + \ },\n \"user\": {\n \"id\": \"5f26f01a-bbee-4202-9298-81261067abbd\"\n },\n\ + \ \"search\":{\n \"query\": \"search term\",\n \"results\": {\n \"items\"\ + : [\n {\n \"document\": {\n \"id\": \"123\",\n \ + \ \"index\": \"products\"\n }\n }\n ],\n \"total_results\"\ + : 10\n },\n \"sort\": {\n \"name\": \"relevance\"\n },\n \"search_application\"\ + : \"website\"\n },\n \"document\":{\n \"id\": \"123\",\n \"index\": \"products\"\ + \n }\n}" diff --git a/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostResponse.ts b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostResponse.ts new file mode 100644 index 0000000000..a4e3a8d7e5 --- /dev/null +++ b/specification/search_application/post_behavioral_analytics_event/BehavioralAnalyticsEventPostResponse.ts @@ -0,0 +1,47 @@ +/* + * Licensed to Elasticsearch B.V. under one or more contributor + * license agreements. See the NOTICE file distributed with + * this work for additional information regarding copyright + * ownership. Elasticsearch B.V. licenses this file to you under + * the Apache License, Version 2.0 (the "License"); you may + * not use this file except in compliance with the License. + * You may obtain a copy of the License at + * + * http://www.apache.org/licenses/LICENSE-2.0 + * + * Unless required by applicable law or agreed to in writing, + * software distributed under the License is distributed on an + * "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY + * KIND, either express or implied. See the License for the + * specific language governing permissions and limitations + * under the License. + */ + +import { UserDefinedValue } from '@spec_utils/UserDefinedValue' + +export class Response { + body: { + accepted: boolean + event?: UserDefinedValue + } + exceptions: [ + { + /** + * Event has been accepted and will be ingested. + */ + statusCodes: [202] + }, + { + /** + * Either the event type is unknown or the event payload contains invalid data. + */ + statusCodes: [400] + }, + { + /** + * Analytics collection does not exist. + */ + statusCodes: [404] + } + ] +}