1. 理解DBFS Put API及其局限性
databricks文件系统（dbfs）是databricks工作区中可用的分布式文件系统，用于存储数据、库和模型。当需要通过api将数据，特别是json等文本内容上传到dbfs时，常用的方法是使用/api/2.0/dbfs/put接口。
API使用要点：
- 内容编码要求： 如果选择通过请求体中的content属性直接传递文件内容，该内容必须是经过Base64编码的字符串。这是API设计上的明确要求，直接传递原始文本或二进制数据会导致各种错误。例如，一个简单的JSON字符串{"key": "value"}在上传前需要先进行Base64编码。
- 文件大小限制： 使用dbfs/put接口直接通过content属性上传文件存在一个显著的限制——文件大小不能超过1MB。对于任何大于此限制的文件，此方法将不再适用。
- 文件上传选项： API文档也提及，如果content属性缺失，API会尝试使用作为HTTP POST请求主体上传的文件。然而，这种方式在实际操作中往往不如直接指定content或使用SDK来得直观和易于管理。
鉴于上述限制，尤其是1MB的文件大小限制和Base64编码的繁琐性，对于生产环境或需要处理大文件的场景，直接使用DBFS Put API通常不是最佳选择。
2. 推荐方案：利用Databricks Python SDK
为了克服直接API调用的局限性并简化DBFS文件操作，Databricks官方强烈推荐使用Databricks Python SDK。该SDK提供了一套高级抽象，能够显著简化文件上传、下载及其他DBFS交互，同时解决了认证管理、大文件处理等复杂问题。
Databricks Python SDK的优势：
立即学习“Python免费学习笔记（深入）”；
- 无缝认证： SDK能够自动处理与Databricks工作区的认证过程，通常通过环境变量或配置文件自动发现认证凭据，无需手动管理API令牌。
- 支持大文件： SDK的upload方法没有1MB的文件大小限制，能够高效地处理大型文件，这对于数据工程师和科学家来说至关重要。
- 简化操作： 提供直观的API接口，如dbfs.upload()和dbfs.download()，使得文件操作代码更加简洁易读。
- 错误处理： 内置了更健壮的错误处理机制，能够更好地管理API调用中可能出现的异常。
示例代码：使用Databricks Python SDK上传与下载文件
以下是一个使用Databricks Python SDK上传文件到DBFS，并随后下载验证的示例。
import io
import pathlib
import time
from databricks.sdk import WorkspaceClient
from databricks.sdk.service import dbfs
# 1. 初始化WorkspaceClient
# SDK会自动从环境变量（如DATABRICKS_HOST, DATABRICKS_TOKEN）或.databrickscfg文件获取认证信息。
w = WorkspaceClient()
# 2. 定义DBFS上的目标路径
# 使用时间戳确保路径的唯一性
root = pathlib.Path(f'/tmp/{time.time_ns()}')
# 3. 创建一个内存中的文件对象作为上传内容
# io.BytesIO 允许我们将字节数据当作文件来处理
file_content = b"This is some text data for testing DBFS upload."
f = io.BytesIO(file_content)
# 4. 使用SDK的dbfs.upload方法上传文件
# 第一个参数是DBFS上的目标路径，第二个参数是文件对象
print(f"Uploading file to DBFS: {root}/01")
w.dbfs.upload(f'{root}/01', f)
print("File uploaded successfully.")
# 5. 使用SDK的dbfs.download方法下载文件并验证
print(f"Downloading file from DBFS: {root}/01")
with w.dbfs.download(f'{root}/01') as downloaded_file:
downloaded_data = downloaded_file.read()
assert downloaded_data == file_content
print("File downloaded and verified successfully.")
print(f"Downloaded content: {downloaded_data.decode('utf-8')}")
# 注意：在实际应用中，可能还需要清理临时文件
# w.dbfs.delete(f'{root}/01', recursive=False)代码解析：
- WorkspaceClient()：这是SDK的入口点，用于与Databricks工作区进行交互。
- io.BytesIO(b"some text data")：创建一个内存中的二进制流，模拟一个文件。在实际应用中，你可以替换为读取本地文件或生成的数据流。
- w.dbfs.upload(f'{root}/01', f)：这是核心的上传操作。它接受DBFS上的目标路径和文件对象作为参数。SDK会处理文件的分块上传和认证。
- w.dbfs.download(f'{root}/01')：用于从DBFS下载文件。它返回一个文件对象，可以使用read()方法获取内容。with语句确保文件资源被正确关闭。
- assert downloaded_data == file_content：验证下载的内容与上传的原始内容是否一致。
3. 最佳实践与注意事项
在Databricks中进行DBFS文件操作时，遵循以下最佳实践可以提高效率和可靠性：
- 优先使用Databricks Python SDK： 对于大多数文件操作场景，尤其是涉及大文件或需要自动化脚本的场景，SDK是比直接API调用更优的选择。它提供了更高级别的抽象，简化了开发，并增强了鲁棒性。
- 理解API限制： 如果确实需要直接使用DBFS Put API，请务必记住1MB的文件大小限制，并确保content属性中的数据经过Base64编码。
- 认证管理： SDK通常能自动处理认证。如果使用直接API，请确保您的API令牌安全存储并正确传递（例如，通过HTTP Authorization头）。
- 路径规范： DBFS路径通常以/开头，例如/tmp/、/FileStore/等。确保您的路径是有效的DBFS路径。
- 错误处理： 在编写文件操作代码时，始终包含适当的错误处理机制（如try-except块），以应对网络问题、权限不足或文件不存在等情况。
- 资源清理： 如果上传的是临时文件，考虑在操作完成后进行清理，以避免不必要的存储占用。
总结
在Databricks中将文件上传到DBFS，可以直接使用DBFS Put API，但需注意其内容Base64编码要求和1MB的文件大小限制。对于更可靠、更高效且能处理大文件的场景，强烈推荐使用Databricks Python SDK。SDK通过提供高级抽象和自动认证管理，极大地简化了DBFS文件操作，是开发人员和数据工程师的首选工具。理解并选择合适的工具，将有助于您更高效地管理Databricks上的数据资源。
