弃用通知

Box Python SDK的此版本处于维护模式，并将很快被弃用，仅提供关键的安全更新和错误修复。我们建议使用新的Box Python SDK版本，可在box/box-python-sdk-gen找到。

您可以在此处找到从Box Python SDK v3.x迁移到新的box-sdk-gen包的迁移指南。如果您有任何问题，请在新的存储库中创建一个问题或在Box开发者支持处获取帮助。

Box Python SDK

入门文档：https://developer.box.com/guides/tooling/sdks/python/

• 安装
• 入门
• 授权
  • 基于JWT的服务器到服务器认证
  • 传统的三脚OAuth2
  • 其他授权选项
• 使用文档
  • 手动制作API调用
• 其他客户端选项
  • 日志客户端
  • 开发者令牌客户端
  • 开发客户端
• 定制
  • 自定义子类
• FIPS 140-2合规性
• 版本
  • 支持版本
  • 版本计划
• 贡献
  • 开发者设置
  • 测试
• 问题、错误和功能请求？
• 版权和许可

安装

pip install boxsdk

SDK的当前版本是v3.x —— 随着此版本的发布，已停止对Python 3.5和更早版本（包括2.x）的支持。如果您正在寻找v1.5.x的代码或文档，请参阅1.5分支。

入门

要开始使用SDK，请从Box开发者控制台中的应用程序配置页面获取开发者令牌。您可以使用此令牌来为您自己的Box账户进行测试调用。

SDK提供了一个交互式的DevelopmentClient，这使得在REPL中测试SDK变得容易。此客户端将在需要时自动提示输入新的开发者令牌，并将记录HTTP请求和响应以帮助调试和了解SDK如何进行API调用。

>>> from boxsdk import DevelopmentClient
>>> client = DevelopmentClient()
Enter developer token: <ENTER DEVELOPER TOKEN HERE>
>>> user = client.user().get()
GET https://api.box.com/2.0/users/me {'headers': {'Authorization': '---wXyZ',
            'User-Agent': 'box-python-sdk-2.0.0',
            'X-Box-UA': 'agent=box-python-sdk/2.0.0; env=python/3.6.5'},
'params': None}
"GET https://api.box.com/2.0/users/me" 200 454
{'Date': 'Thu, 01 Nov 2018 23:32:11 GMT', 'Content-Type': 'application/json', 'Transfer-Encoding': 'chunked', 'Connection': 'keep-alive', 'Strict-Transport-Security': 'max-age=31536000', 'Cache-Control': 'no-cache, no-store', 'Content-Encoding': 'gzip', 'Vary': 'Accept-Encoding', 'BOX-REQUEST-ID': '0b50luc09ahp56m2jmkla8mgmh2', 'Age': '0'}
{'address': '',
'avatar_url': 'https://cloud.app.box.com/api/avatar/large/123456789',
'created_at': '2012-06-07T11:14:50-07:00',
'id': '123456789',
'job_title': '',
'language': 'en',
'login': 'user@example.com',
'max_upload_size': 16106127360,
'modified_at': '2018-10-30T17:01:27-07:00',
'name': 'Example User',
'phone': '',
'space_amount': 1000000000000000.0,
'space_used': 14330018065,
'status': 'active',
'timezone': 'America/Los_Angeles',
'type': 'user'}

>>> print(f'The current user ID is {user.id}')
The current user ID is 123456789

在REPL之外，您可以使用开发者令牌初始化一个新的Client以开始。

from boxsdk import OAuth2, Client

auth = OAuth2(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    access_token='YOUR_DEVELOPER_TOKEN',
)
client = Client(auth)

user = client.user().get()
print(f'The current user ID is {user.id}')

授权

Box API使用OAuth2进行身份验证。SDK使得使用OAuth2令牌相对容易。

基于JWT的服务器到服务器认证

Python SDK支持您的JWT身份验证应用程序。

使用JWT进行身份验证需要一些额外的依赖项。要获取它们，只需

pip install "boxsdk[jwt]"

不要用OAuth2的实例实例化您的Client，而是使用JWTAuth的实例。

from boxsdk import JWTAuth
from boxsdk import Client

auth = JWTAuth(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    enterprise_id='YOUR_ENTERPRISE_ID',
    jwt_key_id='YOUR_JWT_KEY_ID',
    rsa_private_key_file_sys_path='CERT.PEM',
    rsa_private_key_passphrase='PASSPHRASE',
)

access_token = auth.authenticate_instance()
client = Client(auth)

此客户端能够创建应用程序用户

ned_stark_user = client.create_user('Ned Stark')

然后这些用户可以进行身份验证

ned_auth = JWTAuth(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    user=ned_stark_user,
    jwt_key_id='YOUR_JWT_KEY_ID',
    rsa_private_key_file_sys_path='CERT.PEM',
    rsa_private_key_passphrase='PASSPHRASE'
)
ned_auth.authenticate_user()
ned_client = Client(ned_auth)

使用 ned_client 发出的请求（或来自 ned_client 方法的返回对象）将代表新创建的应用用户执行。

传统的三脚OAuth2

获取授权 URL

from boxsdk import OAuth2

oauth = OAuth2(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    store_tokens=your_store_tokens_callback_method,
)

auth_url, csrf_token = oauth.get_authorization_url('http://YOUR_REDIRECT_URL')

store_tokens 是一个用于存储访问令牌和刷新令牌的回调。您可以定义如下

def store_tokens(access_token, refresh_token):
    # store the tokens at secure storage (e.g. Keychain)

SDK 将在 Python 脚本运行期间在内存中保留令牌，因此您不必始终传递 store_tokens。

认证（获取访问/刷新令牌）

如果您将用户导航到 auth_url，用户最终将被重定向到 http://YOUR_REDIRECT_URL?code=YOUR_AUTH_CODE。在获取代码后，您可以使用该代码来交换访问令牌和刷新令牌。

SDK 会为您处理所有工作；您需要做的就是运行

# Make sure that the csrf token you get from the `state` parameter
# in the final redirect URI is the same token you get from the
# get_authorization_url method.
assert 'THE_CSRF_TOKEN_YOU_GOT' == csrf_token
access_token, refresh_token = oauth.authenticate('YOUR_AUTH_CODE')

创建一个认证客户端

from boxsdk import Client

client = Client(oauth)

就这样！您可以使用客户端开始执行各种酷炫的操作，SDK 将自动为您处理令牌刷新。

根据访问令牌和刷新令牌实例化客户端

或者，您可以使用访问令牌和刷新令牌实例化一个 OAuth2 对象。一旦您有了 oauth 对象，您就可以将其传递给 Client 对象以实例化一个客户端并开始调用。

from boxsdk import Client, OAuth2

oauth = OAuth2(
    client_id='YOUR_CLIENT_ID',
    client_secret='YOUR_CLIENT_SECRET',
    access_token='ACCESS_TOKEN',
    refresh_token='REFRESH_TOKEN',
)

client = Client(oauth)
user = client.user().get()

这将检索当前用户！从这里，您可以使用您创建的客户端开始调用。

其他授权选项

对于 SDK 的高级使用，提供了三个额外的认证类

• CooperativelyManagedOAuth2：允许多个认证实例共享令牌。
• RemoteOAuth2：允许在没有访问您应用程序客户端密钥的客户端上使用 SDK。相反，您提供 retrieve_access_token 回调。该回调应执行令牌刷新，例如在具有访问客户端密钥的服务器上。
• RedisManagedOAuth2：在 Redis 中存储访问令牌和刷新令牌。这允许多个进程（可能跨越多台机器）在同步令牌刷新的同时共享访问令牌。例如，这对于多进程 Web 服务器可能很有用。

使用文档

有关可用的功能及其示例代码的完整文档可在 SDK 文档页面 找到，并在 ReadTheDocs 上也有方法级别的文档。

手动制作API调用

Box API 不断演变。因此，存在一些 API 端点，这些端点并非由 SDK 明确支持。您仍然可以使用这些端点通过使用 Client 的 make_request 方法。

# https://developer.box.com/en/reference/get-metadata-templates-id/
# Returns a Python dictionary containing the result of the API request
json_response = client.make_request(
    'GET',
    client.get_url('metadata_templates', 'enterprise', 'customer', 'schema'),
).json()

make_request() 接受两个参数

• method - 一个 HTTP 动词，如 GET 或 POST
• url - 请求的 API 端点的 URL

Client 类和 Box 对象具有 get_url 方法。传递一个端点以获取该对象和端点使用的正确 URL。

对于需要正文或查询参数的 API 调用，您可以使用 **kwargs 传递额外的参数

• data - 接受一个包含正文参数的 json 化字典
• params - 接受一个查询参数的字典

# https://developer.box.com/reference/post-folders/
# Creates a new folder

# JSONify the body
body = json.dumps({
        'name': 'test-subfolder',
        'parent': {
            'id': '0',
        }
})

client.make_request(
    'POST',
    client.get_url('folders'),
    params={'fields': 'name,id'},
    data=body
)

其他客户端选项

日志客户端

要深入了解 SDK 所做的网络调用，您可以使用 LoggingClient 类。此类记录对 Box API 的网络请求和响应信息。

>>> from boxsdk import LoggingClient
>>> client = LoggingClient()
>>> client.user().get()
GET https://api.box.com/2.0/users/me {'headers': {u'Authorization': u'Bearer ---------------------------kBjp',
             u'User-Agent': u'box-python-sdk-1.5.0'},
 'params': None}
{"type":"user","id":"..","name":"Jeffrey Meadows","login":"..",..}
<boxsdk.object.user.User at 0x10615b8d0>

开发者令牌客户端

Box 开发者控制台允许创建短期开发者令牌。SDK 使使用这些令牌变得简单。使用 get_new_token_callback 参数来控制客户端如何根据需要获取新的开发者令牌。默认情况下，提示标准输入获取令牌。

开发客户端

对于探索 Box API 或快速使用 SDK，DevelopmentClient 类将 LoggingClient 与 DeveloperTokenClient 结合使用。

定制

自定义子类

可以定义自定义对象子类

from boxsdk import Client
from boxsdk import Folder

class MyFolderSubclass(Folder):
    pass

client = Client(oauth)
client.translator.register('folder', MyFolderSubclass)
folder = client.folder('0')

>>> print folder
>>> <Box MyFolderSubclass - 0>

如果以这种方式注册对象子类，则从以前返回父类实例的所有SDK方法中返回该子类的实例。有关SDK如何执行动态查找以确定返回类型的示例，请参阅BaseAPIJSONObjectMeta和Translator。

FIPS 140-2合规性

Python SDK 允许使用经过FIPS 140-2验证的SSL库，例如OpenSSL 3.0。但是，需要执行一些操作才能启用此功能。

目前，Python的最新发行版默认使用OpenSSL v1.1.1，它不符合FIPS规范。因此，如果您想在网络通信中使用OpenSSL 3.0，您需要确保Python使用自定义SSL库。实现此目的的一种方法是通过创建一个自定义Python发行版，并用ssl模块替换。

如果您使用JWT进行身份验证，还需要确保作为JWT额外依赖之一的加密库使用OpenSSL 3.0。为了启用cryptography库的FIPS模式，您需要在安装过程中使用pip命令安装FIPS兼容版本的OpenSSL。

版本

我们对所有更改使用修改后的语义版本控制。有关详细信息，请参阅版本策略，该策略自2022年7月30日起生效。

支持版本

仅支持SDK的当前MAJOR版本。新功能、功能、错误修复和安全更新将仅添加到当前MAJOR版本。

当前发布版位于SDK开发的前沿，旨在为积极开发并希望获得最新和最佳功能的客户使用。我们不是为新功能指定发布日期，而是设置最大为2-3个月的固定次要或补丁版本发布节奏（尽管我们可能会更频繁地发布）。同时，没有主要或破坏性发布的计划。相反，我们将提前一个季度通知即将到来的破坏性变更，以便客户可以制定升级计划。我们始终建议所有用户运行当前主版本可用的最新次要版本。我们强烈建议在最早方便的时间以及在EOL日期之前升级到最新SDK主版本。

版本计划

贡献

请参阅CONTRIBUTING.md。

开发者设置

创建虚拟环境并安装包：

mkvirtualenv boxsdk
pip install -r requirements-dev.txt

测试

使用以下方式运行所有测试：

tox

tox测试通过pep8和pylint进行代码风格检查。

tox测试配置为在Python 3.6、3.7、3.8、3.9、3.10、3.11和PyPy上运行（我们的CI配置为在pypy-3.6、pypy-3.7、pypy-3.8上运行PyPy测试）。

问题、错误和功能请求？

需要直接联系我们？浏览问题票据！或者，如果不起作用，提交一个新问题，我们将尽快回复。如果您对Box API有一般性问题，可以在Box开发者论坛上发帖。

版权和许可

Copyright 2019 Box, Inc. All rights reserved.

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

   https://apache.ac.cn/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.