Document PATCH /api/v2/dora/deployments

.generator/schemas/v2/openapi.yaml

@@ -29678,15 +29678,109 @@ components:
         - service
         - started_at
       type: object
+    DORADeploymentPatchByVersionRemediation:
+      description: Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time. Specify either `id` or `version` to identify the remediation deployment, but not both.
+      oneOf:
+        - $ref: "#/components/schemas/DORADeploymentPatchByVersionRemediationByID"
+        - $ref: "#/components/schemas/DORADeploymentPatchByVersionRemediationByVersion"
+    DORADeploymentPatchByVersionRemediationByID:
+      additionalProperties: false
+      description: Remediation details identified by the ID of the remediation deployment.
+      properties:
+        id:
+          description: The ID of the remediation deployment.
+          example: eG42zNIkVjM
+          type: string
+        type:
+          $ref: "#/components/schemas/DORADeploymentPatchRemediationType"
+      required:
+        - id
+        - type
+      type: object
+    DORADeploymentPatchByVersionRemediationByVersion:
+      additionalProperties: false
+      description: Remediation details identified by the version of the remediation deployment, matched against the same service and environment as the failed deployment.
+      properties:
+        type:
+          $ref: "#/components/schemas/DORADeploymentPatchRemediationType"
+        version:
+          description: The version of the remediation deployment.
+          example: v1.2.4
+          type: string
+      required:
+        - version
+        - type
+      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"
+              version: "v1.2.2"
+            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: prod
+          type: string
+        remediation:
+          $ref: "#/components/schemas/DORADeploymentPatchByVersionRemediation"
+        service:
+          description: The name of the service that was deployed.
+          example: my-service
+          type: string
+        version:
+          description: "The version deployed. This can be seen in the Service Catalog or in the APM 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.
+      description: Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time. Specify either `id` or `version` to identify the remediation deployment, but not both.
       properties:
         id:
-          description: The ID of the remediation deployment. Required when the failed deployment must be linked to a remediation deployment.
+          description: The ID of the remediation deployment. Use this or `version` to identify the remediation deployment, but not both.
           example: eG42zNIkVjM
           type: string
         type:
           $ref: "#/components/schemas/DORADeploymentPatchRemediationType"
+        version:
+          description: The version of the remediation deployment, matched against the same service and environment as the failed deployment. Use this or `id` to identify the remediation deployment, but not both.
+          example: v1.2.4
+          type: string
       type: object
     DORADeploymentPatchRemediationType:
       description: The type of remediation action taken. Required when the failed deployment must be linked to a remediation deployment.
@@ -140417,6 +140511,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

@@ -13122,6 +13122,41 @@ datadog\_api\_client.v2.model.dora\_deployment\_object\_attributes module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.dora\_deployment\_patch\_by\_version\_remediation module
+--------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.dora_deployment_patch_by_version_remediation
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.dora\_deployment\_patch\_by\_version\_remediation\_by\_id module
+----------------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.dora_deployment_patch_by_version_remediation_by_id
+   :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,40 @@
+"""
+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_remediation_by_version import (
+    DORADeploymentPatchByVersionRemediationByVersion,
+)
+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_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=DORADeploymentPatchByVersionRemediationByVersion(
+                type=DORADeploymentPatchRemediationType.ROLLBACK,
+                version="v1.2.2",
+            ),
+            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_remediation.py

@@ -0,0 +1,50 @@
+# 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 datadog_api_client.model_utils import (
+    ModelComposed,
+    cached_property,
+)
+
+
+class DORADeploymentPatchByVersionRemediation(ModelComposed):
+    def __init__(self, **kwargs):
+        """
+        Remediation details for the deployment. Optional, but required to calculate failed deployment recovery time. Specify either ``id`` or ``version`` to identify the remediation deployment, but not both.
+
+        :param id: The ID of the remediation deployment.
+        :type id: str
+
+        :param type: The type of remediation action taken. Required when the failed deployment must be linked to a remediation deployment.
+        :type type: DORADeploymentPatchRemediationType
+
+        :param version: The version of the remediation deployment.
+        :type version: str
+        """
+        super().__init__(kwargs)
+
+    @cached_property
+    def _composed_schemas(_):
+        # we need this here to make our import statements work
+        # we must store _composed_schemas in here so the code is only run
+        # when we invoke this method. If we kept this at the class
+        # level we would get an error because the class level
+        # code would be run when this module is imported, and these composed
+        # classes don't exist yet because their module has not finished
+        # loading
+        from datadog_api_client.v2.model.dora_deployment_patch_by_version_remediation_by_id import (
+            DORADeploymentPatchByVersionRemediationByID,
+        )
+        from datadog_api_client.v2.model.dora_deployment_patch_by_version_remediation_by_version import (
+            DORADeploymentPatchByVersionRemediationByVersion,
+        )
+
+        return {
+            "oneOf": [
+                DORADeploymentPatchByVersionRemediationByID,
+                DORADeploymentPatchByVersionRemediationByVersion,
+            ],
+        }