Mud Tools

Appearance

接口名称 ​

部门管理API（租户令牌）- IFeishuTenantV1Departments

功能描述 ​

部门是飞书组织架构里的一个基础实体，每个员工都归属于一个或多个部门。当前接口使用租户令牌访问，适应于租户应用场景。部门在飞书的身份标识包括department_id、open_department_id。

参考文档 ​

https://open.feishu.cn/document/directory-v1/department/overview

函数列表 ​

函数名称功能描述认证方式HTTP方法
CreateDepartmentAsync创建新部门租户令牌POST
UpdateDepartmentAsync更新部门信息租户令牌PATCH
DeleteDepartmentByIdAsync删除指定部门租户令牌DELETE
QueryDepartmentsAsync批量获取部门详细信息租户令牌POST
QueryDepartmentsPageListAsync分页查询部门列表租户令牌POST
SearchEmployeePageListAsync搜索部门信息租户令牌POST

函数详细内容 ​

函数名称：创建部门 ​

函数签名：

csharp
Task<FeishuApiResult<DepartmentCreateUpdateRequest>?> CreateDepartmentAsync(
    [Body] DepartmentCreateUpdateRequest departmentCreateRequest,
    [Query("employee_id_type")] string? employee_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
departmentCreateRequestDepartmentCreateUpdateRequest是创建部门的请求体
employee_id_typestring否用户ID类型，默认为"open_id"
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "department": {
      "department_id": "od-1234567890",
      "name": {"zh_cn": "技术部"},
      "parent_department_id": "0"
    }
  }
}

说明：

  • 用于在企业组织机构中创建新部门，支持设置部门名称、父部门、负责人等信息
  • 使用租户令牌可以访问更广泛的部门数据
  • 父部门为根部门时，parent_department_id应设置为"0"
  • custom_department_id不能以"od-"开头，需符合正则规则：^[a-zA-Z0-9][a-zA-Z0-9_-@.]{0,63}$

代码示例：

csharp
var request = new DepartmentCreateUpdateRequest
{
    Department = new DepartmentInfo
    {
        CustomDepartmentId = "tech_dept_001",
        Name = new I18nContents { ZhCn = "技术部", EnUs = "Technology Department" },
        ParentDepartmentId = "0",
        EnabledStatus = true,
        OrderWeight = "100",
        Leaders = new List<DepartmentLeader>
        {
            new DepartmentLeader { EmployeeId = "ou_1234567890" }
        }
    }
};

var result = await _feishuTenantV1Departments.CreateDepartmentAsync(request);
if (result?.Code == 0)
{
    Console.WriteLine("部门创建成功");
    Console.WriteLine($"部门ID：{result.Data.Department.CustomDepartmentId}");
}

函数名称：更新部门信息 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> UpdateDepartmentAsync(
    [Path] string department_id,
    [Body] DepartmentCreateUpdateRequest departmentUpdateRequest,
    [Query("employee_id_type")] string? employee_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
department_idstring是部门ID
departmentUpdateRequestDepartmentCreateUpdateRequest是更新部门的请求体
employee_id_typestring否用户ID类型，默认为"open_id"
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success"
}

说明：

  • 用于更新企业组织机构部门信息，仅更新显式传参的部分
  • 使用租户令牌可以更新任意部门信息
  • department_id需要与department_id_type的取值保持一致

代码示例：

csharp
var request = new DepartmentCreateUpdateRequest
{
    Department = new DepartmentInfo
    {
        Name = new I18nContents { ZhCn = "研发技术部", EnUs = "R&D Technology Department" },
        OrderWeight = "200",
        EnabledStatus = true,
        Leaders = new List<DepartmentLeader>
        {
            new DepartmentLeader { EmployeeId = "ou_1234567890" },
            new DepartmentLeader { EmployeeId = "ou_1234567891" }
        }
    }
};

var result = await _feishuTenantV1Departments.UpdateDepartmentAsync("tech_dept_001", request);
if (result?.Code == 0)
{
    Console.WriteLine("部门更新成功");
}

函数名称：删除部门 ​

函数签名：

csharp
Task<FeishuNullDataApiResult?> DeleteDepartmentByIdAsync(
    [Path] string department_id,
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
department_idstring是部门ID
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success"
}

说明：

  • 从企业组织机构中删除指定的部门
  • 使用租户令牌可以删除任意部门
  • 删除部门前请确保该部门下没有子部门和员工
  • 此操作不可恢复，请谨慎操作

代码示例：

csharp
var result = await _feishuTenantV1Departments.DeleteDepartmentByIdAsync("tech_dept_001");
if (result?.Code == 0)
{
    Console.WriteLine("部门删除成功");
}
else
{
    Console.WriteLine($"删除失败：{result?.Msg}");
}

函数名称：批量获取部门信息 ​

函数签名：

csharp
Task<FeishuApiResult<DepartmentListResult>?> QueryDepartmentsAsync(
    [Body] DepartmentQueryRequest departmentQueryRequest,
    [Query("employee_id_type")] string? employee_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
departmentQueryRequestDepartmentQueryRequest是部门查询参数请求体
employee_id_typestring否用户ID类型，默认为"open_id"
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "departments": [
      {
        "department_id": "tech_dept_001",
        "name": {"zh_cn": "技术部", "en_us": "Technology Department"},
        "parent_department_id": "0",
        "enabled_status": true,
        "leaders": [
          {"employee_id": "ou_1234567890"}
        ]
      }
    ],
    "abnormals": []
  }
}

说明：

  • 支持传入多个部门ID，返回每个部门的详细信息
  • 使用租户令牌可以获取所有部门的详细信息
  • required_fields参数控制返回的字段列表
  • abnormals字段包含查询过程中发现的异常信息

代码示例：

csharp
var request = new DepartmentQueryRequest
{
    DepartmentIds = new List<string> { "tech_dept_001", "sales_dept_001" },
    RequiredFields = new List<string> 
    { 
        "name", 
        "parent_department_id", 
        "enabled_status",
        "leaders",
        "order_weight",
        "custom_field_values"
    }
};

var result = await _feishuTenantV1Departments.QueryDepartmentsAsync(request);
if (result?.Code == 0)
{
    Console.WriteLine($"成功查询到 {result.Data.Departments.Count} 个部门");
    Console.WriteLine($"异常部门数量：{result.Data.Abnormals.Count}");
    
    foreach (var dept in result.Data.Departments)
    {
        Console.WriteLine($"部门：{dept.Name.ZhCn}，负责人数量：{dept.Leaders?.Count ?? 0}");
    }
}

函数名称：分页查询部门列表 ​

函数签名：

csharp
Task<FeishuApiResult<DepartmentPageListResult>?> QueryDepartmentsPageListAsync(
    [Body] FilterSearchRequest filterSearchRequest,
    [Query("employee_id_type")] string? employee_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
filterSearchRequestFilterSearchRequest是字段过滤查询条件请求体
employee_id_typestring否用户ID类型，默认为"open_id"
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "departments": [
      {
        "department_id": "tech_dept_001",
        "name": {"zh_cn": "技术部"},
        "enabled_status": true
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

  • 用于依据指定条件，批量获取符合条件的部门详情列表
  • 使用租户令牌可以查询所有部门数据
  • 支持分页查询和字段过滤
  • 可以通过filter_conditions设置复杂的过滤条件

代码示例：

csharp
var request = new FilterSearchRequest
{
    FilterConditions = new List<FilterCondition>
    {
        new FilterCondition 
        { 
            Field = "enabled_status", 
            Operator = "eq", 
            Value = true 
        },
        new FilterCondition 
        { 
            Field = "parent_department_id", 
            Operator = "ne", 
            Value = "0" 
        }
    },
    RequiredFields = new List<string> 
    { 
        "name", 
        "parent_department_id", 
        "enabled_status",
        "order_weight"
    },
    PageSize = 20,
    PageToken = "",
    OrderBy = new List<OrderCondition>
    {
        new OrderCondition { Field = "order_weight", Direction = "desc" }
    }
};

var result = await _feishuTenantV1Departments.QueryDepartmentsPageListAsync(request);
if (result?.Code == 0)
{
    Console.WriteLine($"共找到 {result.Data.Departments.Count} 个启用状态的子部门");
    
    if (result.Data.HasMore)
    {
        Console.WriteLine("还有更多数据，使用page_token继续查询");
    }
}

函数名称：搜索部门信息 ​

函数签名：

csharp
Task<FeishuApiResult<DepartmentPageListResult>?> SearchEmployeePageListAsync(
    [Body] PageSearchRequest pageSearchRequest,
    [Query("employee_id_type")] string? employee_id_type = "open_id",
    [Query("department_id_type")] string? department_id_type = "open_department_id",
    CancellationToken cancellationToken = default);

认证：租户令牌

参数：

参数名类型必填说明
pageSearchRequestPageSearchRequest是分页查询参数请求体
employee_id_typestring否用户ID类型，默认为"open_id"
department_id_typestring否部门ID类型，默认为"open_department_id"

响应：

json
{
  "code": 0,
  "msg": "success",
  "data": {
    "departments": [
      {
        "department_id": "tech_dept_001",
        "name": {"zh_cn": "技术研发部"},
        "parent_department_id": "0"
      }
    ],
    "page_token": "next_page_token",
    "has_more": true
  }
}

说明：

  • 用于搜索部门信息，通过部门名称等关键词搜索部门信息
  • 使用租户令牌可以搜索所有部门
  • 支持按部门名称进行模糊搜索
  • 返回符合条件的部门列表，支持分页

代码示例：

csharp
var request = new PageSearchRequest
{
    Query = "技术",
    RequiredFields = new List<string> 
    { 
        "name", 
        "parent_department_id", 
        "enabled_status"
    },
    PageSize = 10,
    PageToken = "",
    OrderBy = new List<OrderCondition>
    {
        new OrderCondition { Field = "name.zh_cn", Direction = "asc" }
    }
};

var result = await _feishuTenantV1Departments.SearchEmployeePageListAsync(request);
if (result?.Code == 0)
{
    Console.WriteLine($"搜索"技术"找到 {result.Data.Departments.Count} 个部门");
    
    foreach (var dept in result.Data.Departments)
    {
        Console.WriteLine($"- {dept.Name.ZhCn}");
    }
    
    // 继续搜索下一页
    if (result.Data.HasMore)
    {
        var nextRequest = new PageSearchRequest
        {
            Query = "技术",
            PageSize = 10,
            PageToken = result.Data.PageToken
        };
        
        var nextResult = await _feishuTenantV1Departments.SearchEmployeePageListAsync(nextRequest);
    }
}