Document PATCH /api/v2/dora/deployments

.generator/schemas/v2/openapi.yaml

@@ -29346,6 +29346,62 @@ components:
         - service
         - started_at
       type: object
+    DORADeploymentPatchByVersionRequest:
+      description: Request to patch a DORA deployment event identified by service, environment, and version.
+      example:
+        data:
+          attributes:
+            change_failure: true
+            env: "production"
+            remediation:
+              type: "rollback"
+            service: "my-service"
+            version: "v1.2.3"
+          type: "dora_deployment_patch_request"
+      properties:
+        data:
+          $ref: "#/components/schemas/DORADeploymentPatchByVersionRequestData"
+      required:
+        - data
+      type: object
+    DORADeploymentPatchByVersionRequestAttributes:
+      description: Attributes for patching a DORA deployment event identified by service, environment, and version.
+      properties:
+        change_failure:
+          description: Indicates whether the deployment resulted in a change failure.
+          example: true
+          type: boolean
+        env:
+          description: The environment the deployment was performed in.
+          example: production
+          type: string
+        remediation:
+          $ref: "#/components/schemas/DORADeploymentPatchRemediation"
+        service:
+          description: The name of the service that was deployed.
+          example: my-service
+          type: string
+        version:
+          description: "The version deployed. This is the same version used to correlate with [APM Deployment Tracking](https://docs.datadoghq.com/tracing/services/deployment_tracking/)."
+          example: v1.2.3
+          type: string
+      required:
+        - service
+        - env
+        - version
+        - change_failure
+      type: object
+    DORADeploymentPatchByVersionRequestData:
+      description: The JSON:API data for patching a deployment identified by service, environment, and version.
+      properties:
+        attributes:
+          $ref: "#/components/schemas/DORADeploymentPatchByVersionRequestAttributes"
+        type:
+          $ref: "#/components/schemas/DORADeploymentPatchRequestDataType"
+      required:
+        - type
+        - attributes
+      type: object
     DORADeploymentPatchRemediation:
       description: Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time.
       properties:
@@ -139542,6 +139598,52 @@ paths:
         permissions:
           - dora_metrics_write
   /api/v2/dora/deployments:
+    patch:
+      description: |-
+        Update a deployment's change failure status, identifying the deployment by its service, environment, and version instead of its ID. Use this to mark a deployment as a change failure or back to stable. You can optionally include remediation details to enable failed deployment recovery time calculation. If multiple deployments match the given service, environment, and version, the most recently finished one is updated.
+      operationId: PatchDORADeploymentByVersion
+      requestBody:
+        content:
+          application/json:
+            examples:
+              default:
+                value:
+                  data:
+                    attributes:
+                      change_failure: true
+                      env: production
+                      service: my-service
+                      version: v1.2.3
+                    type: dora_deployment_patch_request
+            schema:
+              $ref: "#/components/schemas/DORADeploymentPatchByVersionRequest"
+        required: true
+      responses:
+        "202":
+          description: Accepted
+        "400":
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/JSONAPIErrorResponse"
+          description: Bad Request
+        "403":
+          $ref: "#/components/responses/NotAuthorizedResponse"
+        "429":
+          $ref: "#/components/responses/TooManyRequestsResponse"
+      security:
+        - apiKeyAuth: []
+          appKeyAuth: []
+      summary: Patch a deployment event by version
+      tags: ["DORA Metrics"]
+      x-codegen-request-body-name: body
+      x-permission:
+        operator: OR
+        permissions:
+          - dora_metrics_write
+      x-unstable: |-
+        **Note**: This endpoint is in preview and is subject to change.
+        If you have any feedback, contact [Datadog support](https://docs.datadoghq.com/help/).
     post:
       description: |-
         Use this API endpoint to get a list of deployment events.

docs/datadog_api_client.v2.model.rst

@@ -12807,6 +12807,27 @@ datadog\_api\_client.v2.model.dora\_deployment\_object\_attributes module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.dora\_deployment\_patch\_by\_version\_request module
+----------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.dora_deployment_patch_by_version_request
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.dora\_deployment\_patch\_by\_version\_request\_attributes module
+----------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.dora_deployment_patch_by_version_request_attributes
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.dora\_deployment\_patch\_by\_version\_request\_data module
+----------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.dora_deployment_patch_by_version_request_data
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.dora\_deployment\_patch\_remediation module
 -------------------------------------------------------------------------
 

examples/v2/dora-metrics/PatchDORADeploymentByVersion.py

@@ -0,0 +1,37 @@
+"""
+Patch a deployment event by version returns "Accepted" response
+"""
+
+from datadog_api_client import ApiClient, Configuration
+from datadog_api_client.v2.api.dora_metrics_api import DORAMetricsApi
+from datadog_api_client.v2.model.dora_deployment_patch_by_version_request import DORADeploymentPatchByVersionRequest
+from datadog_api_client.v2.model.dora_deployment_patch_by_version_request_attributes import (
+    DORADeploymentPatchByVersionRequestAttributes,
+)
+from datadog_api_client.v2.model.dora_deployment_patch_by_version_request_data import (
+    DORADeploymentPatchByVersionRequestData,
+)
+from datadog_api_client.v2.model.dora_deployment_patch_remediation import DORADeploymentPatchRemediation
+from datadog_api_client.v2.model.dora_deployment_patch_remediation_type import DORADeploymentPatchRemediationType
+from datadog_api_client.v2.model.dora_deployment_patch_request_data_type import DORADeploymentPatchRequestDataType
+
+body = DORADeploymentPatchByVersionRequest(
+    data=DORADeploymentPatchByVersionRequestData(
+        attributes=DORADeploymentPatchByVersionRequestAttributes(
+            change_failure=True,
+            env="production",
+            remediation=DORADeploymentPatchRemediation(
+                type=DORADeploymentPatchRemediationType.ROLLBACK,
+            ),
+            service="my-service",
+            version="v1.2.3",
+        ),
+        type=DORADeploymentPatchRequestDataType.DORA_DEPLOYMENT_PATCH_REQUEST,
+    ),
+)
+
+configuration = Configuration()
+configuration.unstable_operations["patch_dora_deployment_by_version"] = True
+with ApiClient(configuration) as api_client:
+    api_instance = DORAMetricsApi(api_client)
+    api_instance.patch_dora_deployment_by_version(body=body)

src/datadog_api_client/configuration.py

@@ -495,6 +495,7 @@ def __init__(
                 "v2.trigger_deployment_gates_evaluation": False,
                 "v2.update_deployment_gate": False,
                 "v2.update_deployment_rule": False,
+                "v2.patch_dora_deployment_by_version": False,
                 "v2.clone_form": False,
                 "v2.create_and_publish_form": False,
                 "v2.create_form": False,

src/datadog_api_client/v2/api/dora_metrics_api.py

@@ -10,6 +10,7 @@
 from datadog_api_client.configuration import Configuration
 from datadog_api_client.v2.model.dora_deployment_response import DORADeploymentResponse
 from datadog_api_client.v2.model.dora_deployment_request import DORADeploymentRequest
+from datadog_api_client.v2.model.dora_deployment_patch_by_version_request import DORADeploymentPatchByVersionRequest
 from datadog_api_client.v2.model.dora_deployments_list_response import DORADeploymentsListResponse
 from datadog_api_client.v2.model.dora_list_deployments_request import DORAListDeploymentsRequest
 from datadog_api_client.v2.model.dora_deployment_fetch_response import DORADeploymentFetchResponse
@@ -251,6 +252,26 @@ def __init__(self, api_client=None):
             api_client=api_client,
         )
 
+        self._patch_dora_deployment_by_version_endpoint = _Endpoint(
+            settings={
+                "response_type": None,
+                "auth": ["apiKeyAuth", "appKeyAuth"],
+                "endpoint_path": "/api/v2/dora/deployments",
+                "operation_id": "patch_dora_deployment_by_version",
+                "http_method": "PATCH",
+                "version": "v2",
+            },
+            params_map={
+                "body": {
+                    "required": True,
+                    "openapi_types": (DORADeploymentPatchByVersionRequest,),
+                    "location": "body",
+                },
+            },
+            headers_map={"accept": ["*/*"], "content_type": ["application/json"]},
+            api_client=api_client,
+        )
+
     def create_dora_deployment(
         self,
         body: DORADeploymentRequest,
@@ -432,3 +453,19 @@ def patch_dora_deployment(
         kwargs["body"] = body
 
         return self._patch_dora_deployment_endpoint.call_with_http_info(**kwargs)
+
+    def patch_dora_deployment_by_version(
+        self,
+        body: DORADeploymentPatchByVersionRequest,
+    ) -> None:
+        """Patch a deployment event by version.
+
+        Update a deployment's change failure status, identifying the deployment by its service, environment, and version instead of its ID. Use this to mark a deployment as a change failure or back to stable. You can optionally include remediation details to enable failed deployment recovery time calculation. If multiple deployments match the given service, environment, and version, the most recently finished one is updated.
+
+        :type body: DORADeploymentPatchByVersionRequest
+        :rtype: None
+        """
+        kwargs: Dict[str, Any] = {}
+        kwargs["body"] = body
+
+        return self._patch_dora_deployment_by_version_endpoint.call_with_http_info(**kwargs)

src/datadog_api_client/v2/model/dora_deployment_patch_by_version_request.py

@@ -0,0 +1,44 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.dora_deployment_patch_by_version_request_data import (
+        DORADeploymentPatchByVersionRequestData,
+    )
+
+
+class DORADeploymentPatchByVersionRequest(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.dora_deployment_patch_by_version_request_data import (
+            DORADeploymentPatchByVersionRequestData,
+        )
+
+        return {
+            "data": (DORADeploymentPatchByVersionRequestData,),
+        }
+
+    attribute_map = {
+        "data": "data",
+    }
+
+    def __init__(self_, data: DORADeploymentPatchByVersionRequestData, **kwargs):
+        """
+        Request to patch a DORA deployment event identified by service, environment, and version.
+
+        :param data: The JSON:API data for patching a deployment identified by service, environment, and version.
+        :type data: DORADeploymentPatchByVersionRequestData
+        """
+        super().__init__(kwargs)
+
+        self_.data = data

src/datadog_api_client/v2/model/dora_deployment_patch_by_version_request_attributes.py

@@ -0,0 +1,75 @@
+# Unless explicitly stated otherwise all files in this repository are licensed under the Apache-2.0 License.
+# This product includes software developed at Datadog (https://www.datadoghq.com/).
+# Copyright 2019-Present Datadog, Inc.
+from __future__ import annotations
+
+from typing import Union, TYPE_CHECKING
+
+from datadog_api_client.model_utils import (
+    ModelNormal,
+    cached_property,
+    unset,
+    UnsetType,
+)
+
+
+if TYPE_CHECKING:
+    from datadog_api_client.v2.model.dora_deployment_patch_remediation import DORADeploymentPatchRemediation
+
+
+class DORADeploymentPatchByVersionRequestAttributes(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.dora_deployment_patch_remediation import DORADeploymentPatchRemediation
+
+        return {
+            "change_failure": (bool,),
+            "env": (str,),
+            "remediation": (DORADeploymentPatchRemediation,),
+            "service": (str,),
+            "version": (str,),
+        }
+
+    attribute_map = {
+        "change_failure": "change_failure",
+        "env": "env",
+        "remediation": "remediation",
+        "service": "service",
+        "version": "version",
+    }
+
+    def __init__(
+        self_,
+        change_failure: bool,
+        env: str,
+        service: str,
+        version: str,
+        remediation: Union[DORADeploymentPatchRemediation, UnsetType] = unset,
+        **kwargs,
+    ):
+        """
+        Attributes for patching a DORA deployment event identified by service, environment, and version.
+
+        :param change_failure: Indicates whether the deployment resulted in a change failure.
+        :type change_failure: bool
+
+        :param env: The environment the deployment was performed in.
+        :type env: str
+
+        :param remediation: Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time.
+        :type remediation: DORADeploymentPatchRemediation, optional
+
+        :param service: The name of the service that was deployed.
+        :type service: str
+
+        :param version: The version deployed. This is the same version used to correlate with `APM Deployment Tracking <https://docs.datadoghq.com/tracing/services/deployment_tracking/>`_.
+        :type version: str
+        """
+        if remediation is not unset:
+            kwargs["remediation"] = remediation
+        super().__init__(kwargs)
+
+        self_.change_failure = change_failure
+        self_.env = env
+        self_.service = service
+        self_.version = version