Storlets API v1¶
Storlets API 是 Swift API 的扩展。在某些情况下，我们直接使用 Swift API。例如，上传 storlet 是使用 Swift 上传到指定的容器完成的。在其他情况下，我们为现有的 Swift 操作添加 storlets 特定的头部。例如，通过在 Swift 下载操作中添加 ‘X-Run-Storlet’ 头部来在下载时调用 storlet。
Storlets 操作¶
Storlets 存储到名为 ‘storlet’ 的特殊容器中。
注意
Storlets 上传到的容器名称是可配置的。名称 ‘storlet’ 是默认值。
列出所有 Storlets¶
[GET] /v1/{account}/storlet
响应体包含已上传 storlets 的名称列表。响应的 Content-type 是 (text/plain)。
storlet1.jar
storlet2.jar
storlet3.jar
上传新的 Storlet¶
您可以根据 storlet 开发人员指南中的说明，用 Java 或 Python 编写 storlet 并将其上传到对象存储。storlet 上传到名为 ‘storlet’ 的容器，因此 url 中出现 ‘/storlet’。storlet 可能依赖于其他现有的库，这些库必须上传到 ‘dependency’ 容器。
注意
同样，名称 ‘dependency’ 也是默认值，可以配置为其他名称。
上传 storlet 时，X-Object-Meta-Storlet-Dependency 头部需要一个值，该值是逗号分隔的依赖项列表。X-Object-Meta-Storlet-Main 头部的主类名参数指定了定义 storlet 的 invoke 方法的类。对于用 Python 编写的 storlets，此参数应以 Python 模块名称为前缀。例如，如果 storlet 文件名为 ‘mystorlet.py’，则类名必须是 ‘mystorlet.<类名>’。X-Object-Meta-Storlet-Language 头部指定了运行 storlet 的语言。值为 “Python” 或 “Java”。X-Object-Meta-Storlet-Interface-Version 头部应提供并设置为 ‘1.0’。虽然目前未使用，但 X-Object-Meta-Storlet-Object-Metadata 头部必须提供并设置为 ‘no’。有关 invoke 方法签名的详细信息，请参阅 Storlets 开发人员手册。请求的 content-type 应设置为 ‘application/octet-stream’。仅在 Python 中，您可以设置 ‘X-Object-Meta-Storlet-Language-Version’ 以选择您的 Python 解释器版本。
[PUT] /v1/{account}/storlet/{storlet_object_name}
对于用 Java 编写的 storlets
'X-Object-Meta-Storlet-Language': 'Java'
'X-Object-Meta-Storlet-Interface-Version': '1.0'
'X-Object-Meta-Storlet-Dependency': dependencies
'X-Object-Meta-Storlet-Object-Metadata': 'no'
'X-Object-Meta-Storlet-Main': {main_class_name}
'X-Auth-Token': {authorization_token}
对于用 Python 编写的 storlets
'X-Object-Meta-Storlet-Language': 'Python'
'X-Object-Meta-Storlet-Language-Version': '3.6'
'X-Object-Meta-Storlet-Interface-Version': '1.0'
'X-Object-Meta-Storlet-Dependency': dependencies
'X-Object-Meta-Storlet-Object-Metadata': 'no'
'X-Object-Meta-Storlet-Main': {module_name.class_name}
'X-Auth-Token': {authorization_token}
依赖项操作¶
上传新的依赖项¶
您可以创建并上传自己的库来协助运行 storlet。这些依赖项上传到名为 ‘dependency’ 的特殊容器。对于可执行依赖项（例如编译的 c 程序），必须指定 X-Object-Meta-Storlet-Dependency-Permissions 头部。否则，可以省略该头部。包含依赖项的库的名称（即 dependency_name）进入 URI。请求的 content-type 应设置为 ‘application/octet-stream’。
[PUT] /v1/{account}/dependency/{dependency_object_name}
'X-Object-Meta-Storlet-Dependency-Version': '1'
'X-Object-Meta-Storlet-Dependency-Permissions' : '0755'
'X-Auth-Token': {authorization_token}
Storlets 调用¶
一旦 storlet 及其依赖项部署完成，storlet 就可以准备调用了。Storlets 可以通过 3 种方式调用
- 对象下载时调用。
在这种情况下，用户获得存储中对象的转换（而不是实际对象）。GET 的一个用例是匿名化，用户可能除非通过某些 storlet 进行匿名化，否则无法访问某些数据。通常，在对象下载时调用 storlet 时，storlet 将在持有对象副本的存储节点上调用。对此规则的例外情况如下所述。
- 对象上传时调用。
在这种情况下，存储在对象存储中的数据是用户上传对象的转换（而不是原始数据或元数据）。一个典型的用例是元数据丰富，Storlet 从上传的数据中提取特定于格式的元数据，并将其作为 Swift 元数据添加。在对象上传时调用 storlet 时，storlet 将在代理节点上调用，然后再进行复制。因此，计算仅发生一次，而不是每个副本一次。
- 对象复制时调用。
在这种情况下，storlet 对对象存储中的数据进行操作，生成一个新对象。一个典型的用例是从现有的 jpg 中提取缩略图。在复制时调用 storlet 的位置（对象节点或代理节点）与下载情况相同。
以下是上述调用的 API 参考。
对象下载时调用 storlet¶
[GET] /v1/{account}/{container}/{object}
必须提供一个额外的头部（‘X-Run-Storlet’）来告知系统运行 storlet。
'X-Run-Storlet': {storlet_name}
'X-Auth-Token': {authorization_token}
还可以向 storlet 提供参数。有两种方法可以发送参数
通过 URL 查询字符串。例如：/v1/{account}/{container}/{object}?param1=val1¶m2=val2
通过请求头部。例如
'X-Storlet-Parameter-1': 'param1:val1' 'X-Storlet-Parameter-2': 'param2:val2'
以 ‘storlet_’ 开头的参数是不允许的。‘storlet_’ 前缀保留供内部系统使用。
要对对象的某个范围调用 storlet，请使用 ‘X-Storlet-Range’ 头部。例如
'X-Storlet-Range': 'bytes=1-6'
‘X-Storlet-Range’ 可以接受 Swift 可以接受的 HTTP ‘Range’ 头部中的任何值，如 <https://developer.openstack.org/api-ref-objectstorage-v1.html> 中所述。不允许同时指定 HTTP ‘Range’ 头部和 ‘X-Run-Storlet’，结果为 ‘400 Bad Request’
注意
如果对象恰好是 SLO，则 storlet 将在整个对象数据上调用。因此，storlet 在代理节点上调用。
可以对多个对象进行 GET 调用来调用 storlet。这是使用 ‘X-Storlet-Extra-Resources’ 头部完成的，该头部可用于指定逗号分隔的对象路径列表，格式为 <container>/<object>。目前，不支持跨帐户的额外资源。在下面的 GET 示例中，多输入 storlet 将获得 3 个对象输入流。
[GET] /v1/AUTH_1234/my_container/myobject_1
'X-Run-Storlet': 'multiinputstorlet-1.0.jar'
'X-Storlet-Extra-Resources': 'my_other_container/my_other_object', 'my_other_other_container/my_other_other_object'
'X-Auth-Token': {authorization_token}
使用 ‘X-Storlet-Extra-Resources’ 时，storlet 在代理节点上调用。
注意
请参阅 multi-input-storlet 源代码，了解编写处理多个输入的 storlet 的方法。
对象上传时调用 storlet¶
[PUT] /v1/{account}/{container}/{object}
必须提供一个额外的头部（‘X-Run-Storlet’）来告知系统运行 storlet。
'X-Run-Storlet': {storlet_name}
'X-Auth-Token': {authorization_token}
与下载时的调用一样，可以通过 URL 查询字符串或请求头部向 storlet 提供参数。
也可以对多个对象进行 PUT 调用来调用 storlet。这与对象下载期间对多个对象调用 storlet 类似。额外的对象应提前上传到 swift。
[PUT] /v1/AUTH_1234/my_container/myobject_1
'X-Run-Storlet': 'multiinputstorlet-1.0.jar'
'X-Storlet-Extra-Resources': 'my_other_container/my_other_object', 'my_other_other_container/my_other_other_object'
'X-Auth-Token': {authorization_token}
对象复制时调用 storlet¶
Swift 中的对象复制可以使用 PUT 和 COPY 动词完成，如下所示
[PUT] /v1/{account}/{container}/{object}
'X-Copy-From': {source container}/{source object}
[COPY] /v1/{account}/{container}/{object}
'Destination': {dest container}/{dest object}
必须提供一个额外的头部（‘X-Run-Storlet’）来告知系统运行 storlet。
'X-Run-Storlet': {storlet_name}
'X-Auth-Token': {authorization_token}
在 PUT 的情况下，storlet 对出现在 ‘X-Copy-From’ 头部中的对象进行操作，创建出现在请求路径中的对象。在 COPY 的情况下，storlet 对出现在请求路径中的对象进行操作，创建出现在 ‘Destination’ 头部中的对象。
无论使用哪个动词来调用复制，都可以添加 ‘X-Storlet-Extra-Resources’ 头部。因此，例如，可以创建一个对象，它是复制源和额外资源的连接。与下载时的调用一样，使用额外资源时，storlet 在代理节点上调用。
- 目前，在调用复制时指定以下任何头部将导致 ‘400 Bad Request’
‘X-Copy-From-Account’
‘Destination-Account’
‘X-Fresh-Metadata’
仅在代理服务器上执行 storlet¶
使用 ‘X-Storlet-Run-On-Proxy’ 头部强制引擎在代理上调用 storlet，例如：
'X-Storlet-Run-On-Proxy': ''
Storlets ACLs¶
Storlets ACLs 是 Swift 容器读取 acl 的扩展，允许向用户通过 storlet 访问数据。换句话说，除非通过特定的 storlet 进行访问，否则某个用户可能无法访问容器中的对象。设置 storlets ACLs 是使用 POST 动词在容器上完成的，如下所示
[POST] /v1/{account}/{container}
X-Storlet-Container-Read: {user_name}
X-Storlet-Name: {storlet_name}
X-Auth-Token: {authorization_token}
user_name 必须是在 Keystone 中定义的可以检索有效令牌的用户。
- storlet_name 是允许通过其访问的 storlet 的名称。此名称
应与调用 storlet 时指定的名称匹配（请参阅 storlet 调用部分）
- authorization_token 是 POST 请求发起者的令牌，必须具有
设置容器 ACL 的权限
当前，storlet ACL 只能设置为单个用户。可以通过对容器执行 HEAD 请求来将 Storlets ACL 视为任何其他容器读取 ACL。ACL 将显示为 .r:storlets.<用户名>_<storlet名称> 作为 Container-Read-ACL 的一部分。
