使用Python API更新SharePoint文件自定义属性和列

霞舞

发布时间：2025-12-08 11:58:19

506人浏览过

来源于php中文网

原创

使用python api更新sharepoint文件自定义属性和列

本教程详细介绍了如何利用Python API高效地更新SharePoint中文件的自定义属性（即列）。通过提供一个实用的Python函数和详细的使用示例，文章指导读者如何建立SharePoint连接、构建属性字典，并以编程方式修改文件的元数据。这对于需要批量管理或自动化SharePoint文件属性更新的开发者和管理员而言，提供了一个清晰、可操作的解决方案。

在SharePoint环境中，文件通常附带各种元数据，包括系统默认属性和用户自定义的列。这些自定义列对于组织、检索和管理文件至关重要。本教程将指导您如何使用Python编程语言和相应的SharePoint API库来程序化地更新这些自定义文件属性。

前提条件与环境配置

在开始之前，请确保您的开发环境满足以下条件：

Python环境： 已安装Python 3.6或更高版本。
SharePoint Python API库： 本教程的代码示例基于Office365-REST-Python-Client库。您可以通过pip安装：
```
pip install Office365-REST-Python-Client
```
SharePoint认证凭据： 您需要一个拥有足够权限来访问和修改SharePoint站点及文件属性的账户。通常，这意味着需要客户端ID（Client ID）和客户端密钥（Client Secret）或者用户名密码进行认证。本教程示例使用客户端ID和客户端密钥。
SharePoint站点URL： 您的SharePoint站点的基本URL。

核心功能：更新文件自定义属性

以下Python函数 update_sp_file_property 封装了更新SharePoint文件自定义属性的核心逻辑。它接收SharePoint上下文、文件服务器相对路径和包含待更新属性的字典作为参数。

立即学习“Python免费学习笔记（深入）”；

Cutout.Pro

AI驱动的视觉设计平台

下载

import os
from office365.sharepoint.client_context import ClientContext
# 假设您有一个辅助函数来获取ClientContext，例如：
# from your_module import get_client_context

def update_sp_file_property(
    ctx: ClientContext, filepath: str, properties: dict
) -> None:
    """
    更新SharePoint文件的自定义属性（列）。

    Args:
        ctx: SharePoint客户端上下文对象。
        filepath: 文件的服务器相对路径，例如 '/sites/<site_name>/Shared Documents/General/path_to_file'。
        properties: 包含要更新的属性名（作为键）和新值（作为值）的字典。
                    属性名应与SharePoint中自定义列的内部名称（Internal Name）一致。
    Returns:
        None
    """

    print(f"尝试更新文件: {os.path.basename(filepath)}")
    # 获取文件对应的列表项，以便访问其属性
    file_item = ctx.web.get_file_by_server_relative_path(filepath).listItemAllFields

    # 为每个属性构建更新查询
    for k, v in properties.items():
        # 设置属性值，persist_changes=True 确保更改被保存
        file_item.set_property(name=k, value=v, persist_changes=True)
        print(f'已将属性 "{k}" 设置为 "{v}"')

    # 发送批量更新查询
    file_item.update().execute_query()
    print(f'文件 {os.path.basename(filepath)} 的所有指定属性已成功更新。')

函数解析：

ctx: ClientContext：这是与SharePoint站点进行交互的入口点。它包含了认证信息和站点URL。
filepath: str：目标文件的服务器相对路径。例如，如果文件位于 https://yourdomain.sharepoint.com/sites/MySite/Shared Documents/General/document.docx，则 filepath 应为 /sites/MySite/Shared Documents/General/document.docx。
properties: dict：一个字典，其键是SharePoint自定义列的内部名称（Internal Name），值是您想要设置的新值。确保使用内部名称而不是显示名称，因为API通过内部名称来识别列。
更新流程：
1. 通过 ctx.web.get_file_by_server_relative_path(filepath).listItemAllFields 获取文件的列表项（ListItem），因为文件的自定义属性实际上是其关联列表项的字段。
2. 遍历 properties 字典，对每个键值对调用 file_item.set_property(name=k, value=v, persist_changes=True)。persist_changes=True 是关键，它指示API在更新时保存这些更改。
3. 最后，调用 file_item.update().execute_query()。这里，update() 方法将所有 set_property 操作打包成一个请求，execute_query() 则将这个请求发送到SharePoint服务器执行。这种方式比每次设置一个属性就发送一个请求更高效。

使用示例

以下是一个完整的示例，展示了如何配置认证信息，创建SharePoint上下文，定义文件路径和属性，并调用上述函数来更新文件属性。

import os
from office365.sharepoint.client_context import ClientContext
from office365.runtime.auth.client_credential import ClientCredential

# 假设您有一个配置文件 (e.g., config.ini, config.json) 存储敏感信息
# 这里我们直接定义，实际应用中建议从配置文件或环境变量读取
class Config:
    SHAREPOINT = {
        "CLIENT_ID": "YOUR_CLIENT_ID", # 替换为您的SharePoint应用注册的客户端ID
        "CLIENT_SECRET": "YOUR_CLIENT_SECRET", # 替换为您的SharePoint应用注册的客户端密钥
        "BASE_URL": "https://yourdomain.sharepoint.com/sites/YourSiteName" # 替换为您的SharePoint站点URL
    }

cfg = Config() # 实例化配置类

def get_client_context(client_id: str, client_secret: str, base_url: str) -> ClientContext:
    """
    创建并返回SharePoint客户端上下文。
    """
    credentials = ClientCredential(client_id, client_secret)
    ctx = ClientContext(base_url).with_credentials(credentials)
    return ctx

# 定义参数
client_id = cfg.SHAREPOINT["CLIENT_ID"]
client_secret = cfg.SHAREPOINT["CLIENT_SECRET"]
base_url = cfg.SHAREPOINT["BASE_URL"]

# 创建SharePoint上下文进行认证
try:
    ctx = get_client_context(
        client_id=client_id, client_secret=client_secret, base_url=base_url
    )
    # 尝试执行一个简单的查询来验证连接
    ctx.web.get().execute_query()
    print("成功连接到SharePoint！")
except Exception as e:
    print(f"连接SharePoint失败: {e}")
    exit()

# 替换为您要更新的文件的服务器相对路径
# 例如："/sites/MySite/Shared Documents/General/MyDocument.docx"
filepath = "/sites/YourSiteName/Shared Documents/General/path_to_your_file.pdf"

# 定义要更新的属性字典
# 键是SharePoint列的内部名称，值是您要设置的新值
properties_to_update = {
    "Property1InternalName": "Value For Property 1",
    "Property2InternalName": "Value For Property 2",
    "CustomColumnDate": "2023-10-26T10:00:00Z" # 日期时间格式示例
}

# 运行更新函数
try:
    update_sp_file_property(ctx=ctx, filepath=filepath, properties=properties_to_update)
    print("文件属性更新操作完成。")
except Exception as e:
    print(f"更新文件属性时发生错误: {e}")

重要提示：

请务必将示例代码中的 YOUR_CLIENT_ID, YOUR_CLIENT_SECRET, https://yourdomain.sharepoint.com/sites/YourSiteName 和 filepath 替换为您的实际值。
Property1InternalName 和 Property2InternalName 必须替换为您的SharePoint自定义列的内部名称。您可以在SharePoint列表或库设置中找到列的内部名称。

注意事项

权限管理： 确保用于认证的SharePoint应用或用户账户具有足够的权限来修改目标文件及其列表项的属性。通常需要“编辑”或“完全控制”权限。
属性内部名称： 自定义列的内部名称可能与其显示名称不同。在SharePoint列表或库设置中，点击列名进入其设置页面，URL中通常会包含 Field=InternalName 或在浏览器开发者工具中检查列的HTML元素，以找到正确的内部名称。
数据类型匹配： 确保您为属性提供的值与SharePoint中对应列的数据类型匹配。例如，日期时间列需要特定格式的字符串（如ISO 8601），数字列需要数字。
错误处理： 在生产环境中，建议加入更健壮的错误处理机制，例如使用 try-except 块捕获API调用可能抛出的异常，并进行适当的日志记录或回滚操作。
批量操作优化： 虽然本教程中的 update_sp_file_property 函数对单个文件的多个属性进行了批量更新，但如果您需要更新大量文件，可以考虑进一步优化，例如使用SharePoint的批量API或在单个 execute_query() 调用中包含多个文件的更新操作。

总结

通过本教程，您应该已经掌握了如何使用Python和Office365-REST-Python-Client库来程序化地更新SharePoint文件的自定义属性。这种能力对于自动化元数据管理、数据迁移、集成其他系统以及确保SharePoint内容的一致性和可发现性具有重要意义。通过利用Python的强大功能，您可以轻松地构建高效的SharePoint自动化解决方案。

Python 文件写入失败的常见原因及正确处理方式

Python DataFrame 去重：基于时间戳保留每篇文章的最新操作记录

Python中使用try语句写入文件时内容未保存的解决方案

Python 中使用 try 语句写入文件失败的常见原因及最佳实践

Python 中基于时间戳保留每篇文章最新操作记录的去重方法