使用Python API管理SharePoint文件：批量更新自定义属性教程

聖光之護

发布时间：2025-12-14 18:09:09

600人浏览过

来源于php中文网

原创

使用python api管理sharepoint文件：批量更新自定义属性教程

本教程详细介绍了如何使用Python API高效更新SharePoint文件中自定义属性（或称列）。通过构建SharePoint客户端上下文，并利用优化后的Python函数，用户可以为指定文件批量修改或添加元数据信息，实现SharePoint文件属性的自动化管理，提升工作效率和数据治理能力。

引言

SharePoint作为企业级内容管理平台，其文件的自定义属性（也常称为自定义列或元数据）对于组织、检索和管理大量文档至关重要。通过为文件添加如部门、项目名称、状态、版本号等自定义属性，可以极大地增强文件的可发现性和业务价值。然而，当需要批量更新或修改这些属性时，手动操作效率低下且易出错。本教程将指导您如何利用Python API实现SharePoint文件自定义属性的自动化更新，从而提高数据治理的效率和准确性。

环境准备与认证

在开始之前，您需要确保安装了Office365-REST-Python-Client库，这是与SharePoint REST API交互的主要工具。

1. 安装必要的库

如果您尚未安装，请通过pip进行安装：

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

pip install Office365-REST-Python-Client

2. SharePoint客户端上下文 (ClientContext) 的创建

与SharePoint进行交互首先需要建立一个客户端上下文（ClientContext）。这通常涉及提供SharePoint站点的基础URL以及认证凭据。本教程示例将使用客户端ID和客户端密钥进行认证，这是一种常见的应用程序级认证方式。

您需要从SharePoint管理中心或Azure AD注册一个应用程序，并获取以下信息：

AI发型设计

虚拟发型试穿工具和发型模拟器

下载

客户端ID (Client ID)
客户端密钥 (Client Secret)
SharePoint基础URL (Base URL)：例如 https://yourcompany.sharepoint.com

获取到这些信息后，您可以像以下示例一样创建ClientContext：

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

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 = "YOUR_CLIENT_ID"
# client_secret = "YOUR_CLIENT_SECRET"
# base_url = "https://yourcompany.sharepoint.com/sites/yoursite"

# ctx = get_client_context(client_id, client_secret, base_url)

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

我们将实现一个Python函数update_sp_file_property，它能够接收SharePoint客户端上下文、文件的服务器相对路径以及一个包含待更新属性的字典，然后执行更新操作。

1. 函数设计与实现

为了提高效率，我们将一次性获取文件的所有列表项字段（listItemAllFields）对象，然后循环设置所有待更新的属性，最后通过一次API调用提交所有更改。

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

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

    Args:
        ctx: ClientContext 对象，已认证的SharePoint客户端上下文。
        filepath: 文件的服务器相对路径，例如 "/sites/mysite/Shared Documents/General/path_to_file.docx"。
        properties: 包含要更新的属性名称和值的字典。
                    属性名称应与SharePoint中自定义列的内部名称匹配。
    Returns:
        None
    """
    try:
        # 获取文件对象，并进而获取其对应的列表项所有字段
        # 这允许我们修改与文件关联的元数据
        file_item = ctx.web.get_file_by_server_relative_path(filepath).listItemAllFields

        # 遍历所有待更新的属性，并设置到文件列表项中
        for k, v in properties.items():
            file_item.set_property(name=k, value=v, persist_changes=True)
            print(f'准备为文件 "{os.path.basename(filepath)}" 设置属性: "{k}" = "{v}"')

        # 一次性提交所有属性更改
        file_item.update().execute_query()
        print(f'成功更新文件 "{os.path.basename(filepath)}" 的所有指定属性。')

    except Exception as e:
        print(f"更新文件属性时发生错误 '{filepath}': {e}")

2. 函数参数说明

ctx (ClientContext): 这是一个已经通过认证的SharePoint客户端上下文对象。
filepath (str): 这是文件的服务器相对路径。例如，如果您的SharePoint站点是 https://yourcompany.sharepoint.com/sites/mysite，并且文件位于“共享文档”库下的“General”文件夹中，文件名为report.docx，那么其相对路径可能是 /sites/mysite/Shared Documents/General/report.docx。请务必使用正确的相对路径。
properties (dict): 这是一个字典，其中键是SharePoint自定义列的内部名称，值是您希望设置的新值。例如，{"ProjectStatus": "Completed", "Department": "IT"}。

使用示例

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

# 假设 cfg 是一个字典或配置对象，包含SharePoint认证信息
# 例如：
cfg = {
    "SHAREPOINT": {
        "CLIENT_ID": "YOUR_ACTUAL_CLIENT_ID",
        "CLIENT_SECRET": "YOUR_ACTUAL_CLIENT_SECRET",
        "BASE_URL": "https://yourcompany.sharepoint.com/sites/yoursite"
    }
}

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

# 2. 创建SharePoint客户端上下文
try:
    ctx = get_client_context(client_id=client_id, client_secret=client_secret, base_url=base_url)
    ctx.load(ctx.web).execute_query() # 验证连接是否成功
    print(f"成功连接到SharePoint站点: {ctx.web.url}")
except Exception as e:
    print(f"连接SharePoint失败: {e}")
    exit()

# 3. 定义要更新的文件路径和属性
# 注意：filepath是文件的服务器相对路径
# 例如：如果您的站点是 https://yourcompany.sharepoint.com/sites/mysite
# 并且文件在 '共享文档/General' 文件夹下，文件名为 'MyDocument.docx'
# 那么相对路径就是 '/sites/mysite/Shared Documents/General/MyDocument.docx'
filepath_to_update = "/sites/yoursite/Shared Documents/General/MyDocument.docx" 

# 定义要更新的属性字典
# 键是SharePoint列的内部名称，值是要设置的新值
properties_to_update = {
    "ProjectStatus": "已完成",  # 假设有一个名为 'ProjectStatus' 的自定义列
    "ReviewDate": "2023-10-26", # 假设有一个名为 'ReviewDate' 的自定义列
    "DocumentOwner": "张三",     # 假设有一个名为 'DocumentOwner' 的自定义列
}

# 4. 运行更新函数
print(f"\n开始更新文件 '{os.path.basename(filepath_to_update)}' 的属性...")
update_sp_file_property(ctx=ctx, filepath=filepath_to_update, properties=properties_to_update)
print("属性更新操作完成。")

注意事项与最佳实践

服务器相对路径的准确性：文件路径必须是SharePoint服务器上的相对路径，且必须精确。如果路径不正确，get_file_by_server_relative_path将无法找到文件。
属性名称与SharePoint内部列名的匹配：properties字典中的键必须与SharePoint中自定义列的内部名称完全匹配，而不是显示名称。您可以通过访问SharePoint列表或库的“列表设置”或“库设置”找到列的内部名称。
数据类型匹配：确保您为属性提供的值与SharePoint中对应列的数据类型兼容。例如，日期列应提供日期格式的字符串，数字列应提供数字。
错误处理机制：在生产环境中，强烈建议为API调用添加更健壮的错误处理（如try-except块），以捕获网络问题、权限不足或SharePoint返回的特定错误。
权限管理：用于认证的客户端ID和客户端密钥必须拥有对目标SharePoint站点、库和文件的相应编辑权限。至少需要“编辑”或“参与”权限才能修改文件属性。
批量更新多个文件：如果要更新多个文件的属性，可以将文件路径和对应的属性字典组织成一个列表，然后在一个循环中调用update_sp_file_property函数。

总结

通过本教程，您已经学会了如何使用Python API（特别是Office365-REST-Python-Client库）来自动化更新SharePoint文件的自定义属性。这种自动化能力对于管理大量文件、执行数据迁移或集成其他业务系统非常有用。掌握此技能将显著提升您在SharePoint环境中的工作效率和数据管理能力。请记住，始终关注权限、路径和属性名称的准确性，以确保操作的顺利进行。

Python List[int] 在运行时是什么？

Python 类型别名的最佳实践

Python asyncio 事件循环是如何调度任务的？

Python 多进程启动为什么这么慢？

Python 中“浅拷贝”究竟拷贝了什么？