Add partial hierarchy selection to team sync endpoints (#3245)

Co-authored-by: ci.datadog-api-spec <packages@datadoghq.com>

Author: api-clients-generation-pipeline[bot]

.generator/schemas/v2/openapi.yaml

@@ -65885,6 +65885,8 @@ components:
       properties:
         frequency:
           $ref: "#/components/schemas/TeamSyncAttributesFrequency"
+        selection_state:
+          $ref: "#/components/schemas/TeamSyncAttributesSelectionState"
         source:
           $ref: "#/components/schemas/TeamSyncAttributesSource"
         sync_membership:
@@ -65907,6 +65909,14 @@ components:
         - ONCE
         - CONTINUOUSLY
         - PAUSED
+    TeamSyncAttributesSelectionState:
+      description: |-
+        Specifies which teams or organizations to sync. When
+        provided, synchronization is limited to the specified
+        items and their subtrees.
+      items:
+        $ref: "#/components/schemas/TeamSyncSelectionStateItem"
+      type: array
     TeamSyncAttributesSource:
       description: The external source platform for team synchronization. Only "github" is supported.
       enum:
@@ -65916,6 +65926,7 @@ components:
       x-enum-varnames:
         - GITHUB
     TeamSyncAttributesSyncMembership:
+      default: false
       description: Whether to sync members from the external team to the Datadog team. Defaults to `false` when not provided.
       example: true
       type: boolean
@@ -65975,6 +65986,72 @@ components:
             $ref: "#/components/schemas/TeamSyncData"
           type: array
       type: object
+    TeamSyncSelectionStateExternalId:
+      description: The external identifier for a team or organization in the source platform.
+      properties:
+        type:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalIdType"
+        value:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalIdValue"
+      required:
+        - type
+        - value
+      type: object
+    TeamSyncSelectionStateExternalIdType:
+      description: |-
+        The type of external identifier for the selection state item.
+        For GitHub synchronization, the allowed values are `team` and
+        `organization`.
+      enum:
+        - team
+        - organization
+      example: team
+      type: string
+      x-enum-varnames:
+        - TEAM
+        - ORGANIZATION
+    TeamSyncSelectionStateExternalIdValue:
+      description: |-
+        The external identifier value from the source
+        platform. For GitHub, this is the string
+        representation of a GitHub organization ID or team
+        ID.
+      example: "1"
+      type: string
+    TeamSyncSelectionStateItem:
+      description: Identifies a team or organization hierarchy to include in synchronization.
+      properties:
+        external_id:
+          $ref: "#/components/schemas/TeamSyncSelectionStateExternalId"
+        operation:
+          $ref: "#/components/schemas/TeamSyncSelectionStateOperation"
+        scope:
+          $ref: "#/components/schemas/TeamSyncSelectionStateScope"
+      required:
+        - external_id
+      type: object
+    TeamSyncSelectionStateOperation:
+      description: |-
+        The operation to perform on the selected hierarchy.
+        When set to `include`, synchronization covers the
+        referenced teams or organizations.
+      enum:
+        - include
+      example: include
+      type: string
+      x-enum-varnames:
+        - INCLUDE
+    TeamSyncSelectionStateScope:
+      description: |-
+        The scope of the selection. When set to `subtree`,
+        synchronization includes the referenced team or
+        organization and everything nested under it.
+      enum:
+        - subtree
+      example: subtree
+      type: string
+      x-enum-varnames:
+        - SUBTREE
     TeamTarget:
       description: "Represents a team target for an escalation policy step, including the team's ID and resource type."
       properties:
@@ -105434,12 +105511,6 @@ paths:
           description: OK
         "403":
           $ref: "#/components/responses/ForbiddenResponse"
-        "404":
-          content:
-            application/json:
-              schema:
-                $ref: "#/components/schemas/APIErrorResponse"
-          description: Team sync configurations not found
         "429":
           $ref: "#/components/responses/TooManyRequestsResponse"
       security:
@@ -105456,13 +105527,17 @@ paths:
           - teams_read
     post:
       description: |-
-        This endpoint attempts to link your existing Datadog teams with GitHub teams by matching their names.
+        This endpoint configures synchronization between your existing Datadog teams and GitHub teams by matching their names.
         It evaluates all current Datadog teams and compares them against teams in the GitHub organization
         connected to your Datadog account, based on Datadog Team handle and GitHub Team slug
         (lowercased and kebab-cased).
 
         This operation is read-only on the GitHub side, no teams will be modified or created.
 
+        Optionally, provide `selection_state` to limit synchronization
+        to specific teams or organizations and their subtrees, instead
+        of syncing all teams.
+
         [A GitHub organization must be connected to your Datadog account](https://docs.datadoghq.com/integrations/github/),
         and the GitHub App integrated with Datadog must have the `Members Read` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug
         using a normalized exact match; case is ignored and spaces are removed. No modifications are made
@@ -105477,6 +105552,8 @@ paths:
       responses:
         "200":
           description: OK
+        "204":
+          description: No Content
         "403":
           $ref: "#/components/responses/ForbiddenResponse"
         "429":

docs/datadog_api_client.v2.model.rst

@@ -30468,6 +30468,41 @@ datadog\_api\_client.v2.model.team\_sync\_response module
    :members:
    :show-inheritance:
 
+datadog\_api\_client.v2.model.team\_sync\_selection\_state\_external\_id module
+-------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_selection_state_external_id
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.team\_sync\_selection\_state\_external\_id\_type module
+-------------------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_selection_state_external_id_type
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.team\_sync\_selection\_state\_item module
+-----------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_selection_state_item
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.team\_sync\_selection\_state\_operation module
+----------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_selection_state_operation
+   :members:
+   :show-inheritance:
+
+datadog\_api\_client.v2.model.team\_sync\_selection\_state\_scope module
+------------------------------------------------------------------------
+
+.. automodule:: datadog_api_client.v2.model.team_sync_selection_state_scope
+   :members:
+   :show-inheritance:
+
 datadog\_api\_client.v2.model.team\_target module
 -------------------------------------------------
 

examples/v2/teams/SyncTeams_3215592344.py

@@ -1972,13 +1972,17 @@ def sync_teams(
     ) -> None:
         """Link Teams with GitHub Teams.
 
-        This endpoint attempts to link your existing Datadog teams with GitHub teams by matching their names.
+        This endpoint configures synchronization between your existing Datadog teams and GitHub teams by matching their names.
         It evaluates all current Datadog teams and compares them against teams in the GitHub organization
         connected to your Datadog account, based on Datadog Team handle and GitHub Team slug
         (lowercased and kebab-cased).
 
         This operation is read-only on the GitHub side, no teams will be modified or created.
 
+        Optionally, provide ``selection_state`` to limit synchronization
+        to specific teams or organizations and their subtrees, instead
+        of syncing all teams.
+
         `A GitHub organization must be connected to your Datadog account <https://docs.datadoghq.com/integrations/github/>`_ ,
         and the GitHub App integrated with Datadog must have the ``Members Read`` permission. Matching is performed by comparing the Datadog team handle to the GitHub team slug
         using a normalized exact match; case is ignored and spaces are removed. No modifications are made

src/datadog_api_client/v2/api/teams_api.py

@@ -3,7 +3,7 @@
 # Copyright 2019-Present Datadog, Inc.
 from __future__ import annotations
 
-from typing import Union, TYPE_CHECKING
+from typing import List, Union, TYPE_CHECKING
 
 from datadog_api_client.model_utils import (
     ModelNormal,
@@ -15,6 +15,7 @@
 
 if TYPE_CHECKING:
     from datadog_api_client.v2.model.team_sync_attributes_frequency import TeamSyncAttributesFrequency
+    from datadog_api_client.v2.model.team_sync_selection_state_item import TeamSyncSelectionStateItem
     from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
     from datadog_api_client.v2.model.team_sync_attributes_type import TeamSyncAttributesType
 
@@ -23,18 +24,21 @@ class TeamSyncAttributes(ModelNormal):
     @cached_property
     def openapi_types(_):
         from datadog_api_client.v2.model.team_sync_attributes_frequency import TeamSyncAttributesFrequency
+        from datadog_api_client.v2.model.team_sync_selection_state_item import TeamSyncSelectionStateItem
         from datadog_api_client.v2.model.team_sync_attributes_source import TeamSyncAttributesSource
         from datadog_api_client.v2.model.team_sync_attributes_type import TeamSyncAttributesType
 
         return {
             "frequency": (TeamSyncAttributesFrequency,),
+            "selection_state": ([TeamSyncSelectionStateItem],),
             "source": (TeamSyncAttributesSource,),
             "sync_membership": (bool,),
             "type": (TeamSyncAttributesType,),
         }
 
     attribute_map = {
         "frequency": "frequency",
+        "selection_state": "selection_state",
         "source": "source",
         "sync_membership": "sync_membership",
         "type": "type",
@@ -45,6 +49,7 @@ def __init__(
         source: TeamSyncAttributesSource,
         type: TeamSyncAttributesType,
         frequency: Union[TeamSyncAttributesFrequency, UnsetType] = unset,
+        selection_state: Union[List[TeamSyncSelectionStateItem], UnsetType] = unset,
         sync_membership: Union[bool, UnsetType] = unset,
         **kwargs,
     ):
@@ -54,6 +59,11 @@ def __init__(
         :param frequency: How often the sync process should be run. Defaults to ``once`` when not provided.
         :type frequency: TeamSyncAttributesFrequency, optional
 
+        :param selection_state: Specifies which teams or organizations to sync. When
+            provided, synchronization is limited to the specified
+            items and their subtrees.
+        :type selection_state: [TeamSyncSelectionStateItem], optional
+
         :param source: The external source platform for team synchronization. Only "github" is supported.
         :type source: TeamSyncAttributesSource
 
@@ -65,6 +75,8 @@ def __init__(
         """
         if frequency is not unset:
             kwargs["frequency"] = frequency
+        if selection_state is not unset:
+            kwargs["selection_state"] = selection_state
         if sync_membership is not unset:
             kwargs["sync_membership"] = sync_membership
         super().__init__(kwargs)

src/datadog_api_client/v2/model/team_sync_attributes.py

@@ -0,0 +1,55 @@
+# 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.team_sync_selection_state_external_id_type import (
+        TeamSyncSelectionStateExternalIdType,
+    )
+
+
+class TeamSyncSelectionStateExternalId(ModelNormal):
+    @cached_property
+    def openapi_types(_):
+        from datadog_api_client.v2.model.team_sync_selection_state_external_id_type import (
+            TeamSyncSelectionStateExternalIdType,
+        )
+
+        return {
+            "type": (TeamSyncSelectionStateExternalIdType,),
+            "value": (str,),
+        }
+
+    attribute_map = {
+        "type": "type",
+        "value": "value",
+    }
+
+    def __init__(self_, type: TeamSyncSelectionStateExternalIdType, value: str, **kwargs):
+        """
+        The external identifier for a team or organization in the source platform.
+
+        :param type: The type of external identifier for the selection state item.
+            For GitHub synchronization, the allowed values are ``team`` and
+            ``organization``.
+        :type type: TeamSyncSelectionStateExternalIdType
+
+        :param value: The external identifier value from the source
+            platform. For GitHub, this is the string
+            representation of a GitHub organization ID or team
+            ID.
+        :type value: str
+        """
+        super().__init__(kwargs)
+
+        self_.type = type
+        self_.value = value

src/datadog_api_client/v2/model/team_sync_selection_state_external_id.py

@@ -0,0 +1,40 @@
+# 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 (
+    ModelSimple,
+    cached_property,
+)
+
+from typing import ClassVar
+
+
+class TeamSyncSelectionStateExternalIdType(ModelSimple):
+    """
+    The type of external identifier for the selection state item.
+        For GitHub synchronization, the allowed values are `team` and
+        `organization`.
+
+    :param value: Must be one of ["team", "organization"].
+    :type value: str
+    """
+
+    allowed_values = {
+        "team",
+        "organization",
+    }
+    TEAM: ClassVar["TeamSyncSelectionStateExternalIdType"]
+    ORGANIZATION: ClassVar["TeamSyncSelectionStateExternalIdType"]
+
+    @cached_property
+    def openapi_types(_):
+        return {
+            "value": (str,),
+        }
+
+
+TeamSyncSelectionStateExternalIdType.TEAM = TeamSyncSelectionStateExternalIdType("team")
+TeamSyncSelectionStateExternalIdType.ORGANIZATION = TeamSyncSelectionStateExternalIdType("organization")