openstack storlet文档（五）：storlet API

本部分主要介绍API，包括 storlet的操作( list、upload),dependency的操作（upload），storlet请求操作(在对象upload或download时）以及storlet ACL。

Storlets API v1

storlets API是Swift API的扩展。在某些情况下，我们使用Swift API。例如，使用Swift上传到指定的容器来完成上传storlet。在其他情况下，我们在特定的Swift操作中添加了特定的头部。例如，通过将“X-Run-Storlet”头添加到Swift下载操作中，可以进行下载时进行调用。

Operations on Storlets

Storlets存储到名为“storlet”的特殊容器中

Note: storlet上传的容器的名称是可配置的。名称“storlet”只是是默认值。

List All Storlets

[GET] /v1/{account}/storlet

响应的正文包含已上传的storlet的名称列表。响应的内容类型是(text/plain)。

storlet1.jar
storlet2.jar
storlet3.jar

Upload a New Storlet

您可以根据storlet开发人员指南中的说明，以Java或Python编写一个storlet，并将其上传到Object Store。该storlet被上传到名为“storlet”的容器，所以’/ storlet’出现在url中。the storlet可能依赖于其他现有的库，它们必须上传到“dependency”容器。

Note: 再次注意，名称“dependency”是默认值，可以进行不同的配置

上传一个storlet时，X-Object-Meta-Storlet-Dependency头需要一个逗号分隔的dependency列表。X-Object-Meta-Storlet-Main 头部的main_class_name参数指定了在其中定义了storlet的invoke方法所在的类。对于python编写的存sotrlet，此参数应以python模块名称为前缀。例如，如果storlet文件名为“mystorlet.py”，那么类名必须是“mystorlet.“. X-Object-Meta-Storlet-Language头指定了运行该库的语言。“Python”或“Java”可用于该值。应提供X-Object-Meta-Storlet-Interface-Version头文件并将其设置为值“1.0”。尽管目前未使用X-Object-Meta-Storlet-Object-Metadata头，但必须提供并设置为“no”。有关invoke方法签名的详细信息，请参阅Storlets开发人员手册。request的内容类型应设置为“application / octet-stream”。

[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-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}

Operations on dependencies

Upload a New Dependency

您可以创建和上传自己的库来协助运行一个storlet。这些dependencies被上传到一个名为“dependency”的特殊容器。对于executable dependency（如编译的c程序），必须指定 X-Object-Meta-Storlet-Dependency-Permissions头。否则,这个头部可能被省略。包含dependency的库的名称（即dependency_name）进入URI。请求的内容类型应设置为“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 Invocation

一旦存储了storlet和它的依赖关系，这个storlet就可以被调用了。可以通过三种方式调用Storlets：

对象下载时调用。
在这种情况下，用户获取驻留在存储中的对象经过变换后的数据（与实际对象相反）。GET的一个用例是匿名化，用户可能无法访问某些数据，除非它被某些storlet匿名化了。通常，当在对象下载时调用storlet时，将在保存对象的副本的存储节点上调用该storlet。(即一般在对象下载时会在storage node上调用storlet）此规则的例外情况详述如下。
对象上传时调用。
在这种情况下，保存在对象存储中的数据是用户上传的对象经过变换后的结果（与原始数据或元数据相反）。典型的用例是元数据丰富(metadata enrichment )，其中Storlet从上传的数据中提取格式特定的元数据，并将其添加为Swift元数据。在对象上传时调用storlet时，在复制之前,将在代理节点上调用该storlet。因此，计算只发生一次，而不是每个副本一次。
对象复制时调用
在这种情况下，storlet作用于对象存储中的数据，生成新对象。典型的用例是从现有的jpg提取缩略图。调用storlet的副本的位置与下载情况相同（对象节点或代理节点）（The location where the storlet is invoked on copy (object node or proxy node) is the same as for the download case.）

以下是上述调用的API参考。

Invoke a storlet upon object download

[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＆param2 = 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”头提供的任何值，如http://developer.openstack.org/api-ref-objectstorage-v1.html中所述。与“X-Run-Storlet”一起指定HTTP“Range”头是不允许的，并导致“400 Bad Request”

Note: 如果对象恰好是SLO，则在整个对象数据上调用该storlet。因此，应在代理节点上调用该storlet。

在GET时可以在不止一个对象调用storlet。这可以使用“X-Storlet-Extra-Resources”头完成，使用指定的逗号分隔的对象路径的list，形式如<container> / <object>。目前，不支持跨account extra resources(Currently, cross account extra resources are not supported.) 在下面的GET示例中，multi input 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。

Note: 请参阅multi-input-storlet 资源，以编写处理多个输入的storlet。

Invoke a storlet upon object upload

[PUT] /v1/{account}/{container}/{object}

必须提供额外的头部（’X-Run-Storlet’），以通知系统运行一个storlet。

'X-Run-Storlet': {storlet_name}
'X-Auth-Token': {authorization_token}

与下载时的调用一样，可以通过URL查询字符串或通过请求头提供参数。

Invoke a storlet upon object copy

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”头中出现的对象进行打包。

独立于用于调用副本的动词(Independently of the verb used to invoke a copy,),允许人们添加“X-Storlet-Extra-Resources”头文件。因此，人们可以比如创建一个对象，它是copy source和extra resources的连接。与在downlod上的调用一样，当使用额外的资源时，在代理节点上调用该storlet。

目前，在复制时调用storlet，指定下面的任何头将导致“400错误请求”

'X-Copy-From-Account'
'Destination-Account'
'X-Fresh-Metadata'

Executing a storlet on proxy servers only

使用‘X-Storlet-Run-On-Proxy’头来强制引擎在代理服务器上调用storlet，例如：

'X-Storlet-Run-On-Proxy': ''

Storlets ACLs

Storlets ACL是Swift的容器读取acl的扩展，允许用户通过storlet访问数据。换句话说，某个用户可能无法访问从容器读取对象，除非通过特定的storlet完成访问。设置storlet ACL通过使用容器上的POST verb完成ACL，如下所示：

[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 invocation）
authorization_token是POST请求启动器的标志，它必须具有设置容器ACL的权限

目前，只能为单个用户设置一个storlet ACL。通过在容器上执行HEAD请求，可以将Storlets ACL视为任何其他容器读取ACL。作为Container-Read-ACL的一部分，ACL将显示为.r:storlets.<user_name> _<storlet_name>