开发者中心

二进制数据

设备清单可以存储二进制数据, 以下API没有包含在"/inventory"中。

二进制数据接口组成:

  • 二进制数据集合 用于已上传和要上传的二进制数据集合。
  • 二进制数据 用于表示可下载, 更新或删除的二进制数据。

注意: 所有的PUT/POST请求必须设置accept头, 否则会返回空的应答正文。

二进制数据集合

二进制数据集合 [application/vnd.com.nsn.cumulocity.managedObjectCollection+json]
名称 类型 次数 描述
self URI 1 此资源的链接地址。
managedObjects ManagedObject 0..n 二进制数据对象的列表, 如下所示。
statistics PagingStatistics 1 分页统计信息。
prev URI 0..1 上一页链接。
next URI 0..1 下一页链接。
GET - 查询二进制数据集合

应答正文: 托管对象集合

所需角色: ROLE_INVENTORY_READ

请求示例:

GET /inventory/binaries
                    Host: ...
                    Authorization: Basic ...
                  

应答示例:

HTTP/1.1 200 OK
                    Content-Type: application/vnd.com.nsn.cumulocity.applicationCollection+json;ver=...
                    Content-Length: ...
                    {
                    "self" : "...",
                    "next" : "...",
                    "prev" : "...",
                    "managedObjects": [
                    {
                    "self": "<<Object 1 URL>>",
                    "id": "1",
                    "name": "my_picture.png",
                    "type": "image/png",
                    ...
                    "_attachments": {
                    "my_picture.png": {
                    "stub": true,
                    "length": 211952,
                    "digest": "md5-xyz==",
                    "revpos": 2,
                    "content_type": "image/png"
                  }
                }
              },
              {
              "self": "<<Object 2 URL>>",
              "id": "2",
              "name": "my_compressed_file.zip",
              "type": "application/zip",
              ...
              "_attachments": {
              "my_compressed_file.zip": {
              "stub": true,
              "length": 21152,
              "digest": "md5-xyz==",
              "revpos": 2,
              "content_type": "application/zip"
            }
          }
        }
        ],
        "statistics": {
        "currentPage": 1,
        "pageSize": 5,
        "totalPages": 1
      }
    }
  
POST - 上传新二进制数据

请求正文: Multipart

应答正文: 托管对象

所需角色: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

上传二进制数据需要包含以下值的multipart:

  • object 包含托管对象,此托管对象含有文件信息。
  • filesize 包含二进制数据的大小(字节)。
  • file 包含要上传的二进制数据(为正确存储文件, mime类型要和文件相符)。

请求示例:

POST /invenotry/binaries
    Host: ...
    Authorization: Basic ...
    Content-Length: ...
    Content-Type: multipart/form-data; boundary=--myBoundary

    --myBoundary
    Content-Disposition: form-data; name="object"

    {
    "name":"my-file.pdf",
    "type":"application/pdf",
    ...
  }
  --myBoundary
  Content-Disposition: form-data; name="filesize"

  217152
  --myBoundary
  Content-Disposition: form-data; name="file"; filename="my-file.pdf"
  Content-Type: application/pdf

  <<文件内容>>
  --myBoundary

应答示例:

HTTP/1.1 201 Created
  Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json;ver=...
  Content-Length: ...
  Location: <<URL of new managed object>>

  {
  "self": "<<Object 3 URL>>",
  "id": "3",
  "name":"my-file.pdf",
  "type":"application/pdf",
  ...
}

二进制数据

GET - 下载二进制数据

应答正文: 二进制数据

所需角色: ROLE_INVENTORY_READ

请求示例:

GET /inventory/binaries/<<binaryId>>
 ...

应答示例:

HTTP/1.1 200 OK
  Content-Type: <<depending on binary mime type>>
  Content-Length: ...
  Content-Disposition: attachment; filename="myfile.ext"

  ...
PUT - 替换二进制数据

请求正文: 二进制数据

应答报文: 托管对象

所需角色: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

PUT请求将只替换关联托管对象的二进制数据。 要修改托管对象, 可以直接参照更新托管对象操作。

请求示例:

PUT /inventory/binaries/<<binaryId>>
    Host: ...
    Authorization: Basic ...
    Content-Length: ...
    Content-Type: <<depending on binary mime type>>

    ...
  
DELETE - 删除二进制数据

请求正文: N/A.

应答正文: N/A.

所需角色: ROLE_INVENTORY_ADMIN or ROLE_INVENTORY_CREATE

注意: 此请求将删除二进制数据和关联的托管对象

请求示例:

DELETE /inventory/binaries/<<binaryId>>
    Host: ...
    Authorization: Basic ...
  

应答示例:

HTTP/1.1  204 NO CONTENT
  

应用程序插件二进制数据

二进制数据 [multipart/form-data]
POST - 添加一个插件

上传插件会在已有的活跃应用程序中增加插件, 合并内容到特定路径并更新应用程序版本。 上传的插件必须有内容。 插件路径名和url中的"plugin_name"相同。 应答包含托管对象,此托管对象包含应用程序内容。

请求正文: Multipart

应答正文: 托管对象

所需角色: ROLE_APPLICATION_MANAGEMENT_ADMIN

请求示例:

POST /application/applications/<<application_id>>/binaries/plugins/<<plugin_name>> HTTP/1.1
      Accept: application/vnd.com.nsn.cumulocity.managedObject+json
      Content-Type: multipart/form-data; boundary=myBoundary
      Content-Disposition: form-data; name="file"
      Content-Length: 742
      Authorization: Basic ...

      --myBoundary
      Content-Disposition: form-data; name="file"; filename="hello-world-application.zip"
      Content-Type: application/zip

      ... zip内容 ...
      --myBoundary--
    

应答示例:

HTTP/1.1 201 Created
      Location: .../application/applications/{{application_id}}/binaries/{{id}}
      Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

      {... 托管对象内容 ...}
    
DELETE - 删除插件

删除插件会删除插件路径并更新应用程序版本。 插件路径和url中的"plugin_name"相同。 应答包含托管对象,此托管对象包含应用程序内容。

应答正文: 托管对象

所需角色: ROLE_APPLICATION_MANAGEMENT_ADMIN

请求示例:

DELETE /application/applications/<<应用程序id>>/binaries/plugins/<<插件名>> HTTP/1.1
        Authorization: Basic ...
      

应答示例:

HTTP/1.1 200 OK
        Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

        {... 托管对象内容 ...}
      
GET - 查询所有插件

通过返回应用程序根目录下的插件路径名方式返回插件列表。 此外, 如果路径包含cumulocity.json, 此文件内容包含在应答中。

应答正文: 插件列表

所需角色: ROLE_APPLICATION_MANAGEMENT_READ

请求示例:

GET /application/applications/<<应用程序id>>/binaries/plugins HTTP/1.1
          Authorization: Basic ...
        

应答示例:

HTTP/1.1 200 OK
          Content-Type: application/json

          [
          {
          pluginName: 'myfolder'
        },
        {
        pluginName: 'plugin',
        pluginPackage: {'this is the content of cumulocity.json inside plugin folder'}
      }
      ]
    
POST - 更新应用程序文件

增加或更新应用程序文件路径下的文件。 应答包含托管对象,此托管对象包含应用程序内容。

请求正文: Multipart

应答正文: 托管对象

所需角色: ROLE_APPLICATION_MANAGEMENT_ADMIN

请求示例:

POST /application/applications/<<应用程序id>>/binaries/files HTTP/1.1
        Accept: application/vnd.com.nsn.cumulocity.managedObject+json
        Content-Type: multipart/form-data; boundary=myBoundary
        Content-Disposition: form-data; name="filepath"
        Content-Length: 742
        Authorization: Basic ...

        --myBoundary
        Content-Disposition: form-data; name="filepath"; filename="index.html"

        ... zip content ...
        --myBoundary--
      

应答示例:

HTTP/1.1 201 Created
        Location: .../application/applications/{{应用程序id}}/binaries/{{id}}
        Content-Type: application/vnd.com.nsn.cumulocity.managedObject+json; charset=UTF-8; ver=0.9

        {... 托管对象内容 ...}