自定义 Facet(预览)

使用自定义 Facet,可以在项上存储你自己的元数据。 这可用于跟踪自定义状态以及项,并关联到其他系统中的相关项等。 如同 OneDrive 自己的 Facet 一样,自定义 Facet 采用架构,这样可以确保数据保持一致性和有效性,即使用于多个应用,也不例外。

注意: 目前,自定义 Facet 处于预览阶段,仅适用于 OneDrive 个人版。

读取自定义 Facet

必须在 select 查询参数中明确列出 Facet 名称,才能查看某项上的自定义 Facet。 虽然自定义 Facet 与常规 Facet 一起显示,但不会一起返回,除非在 select 语句中添加。

示例

GET /drive/items/{item-id}?select=id,name,image,contoso_oilChange

响应

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

{
 "id": "beefbeef!123",
 "name": "atom.jpg",
 "image": {
     "height": 1200,
     "width": 1600
 },
 "contoso_oilChange": {
     "lastOilChangeDateTime": "2014-07-06T18:05:33.79Z",
     "lastOilChangeMileage": 6785.3,
     "brand": "fabrikam",
     "viscosity": "5w-30"
 }
}

写入自定义 Facet

可以对创建更新调用提供自定义 Facet,就像常规 Facet 一样。 可以在同一调用中同时提供自定义 Facet 和常规 Facet。

示例

PATCH /drive/items/{item-id}
Content-Type: application/json

{
   "contoso_oilChange": {
     "lastOilChangeDateTime": "2015-08-01T20:17:12.86Z",
     "lastOilChangeMileage": 9523.9
   }
 }

响应

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

{
  "id": "12345",
  "name": "foo",
  "image": {
    "height": 1080,
    "width": 1920
  },
  "contoso_oilChange": {
    "lastOilChangeDateTime": "2015-08-01T20:17:12.86Z",
    "lastOilChangeMileage": 9523.9
  }
}

架构注册

必须先定义并向 OneDrive 注册新自定义 Facet 的架构,然后才能使用。 若要注册自定义 Facet,请联系 OneDrive Facet 注册小组,并提供 client_id 和架构定义 JSON。

示例架构定义如下。

{
    "name": "contoso_oilChange",
    "description": "Stores info about the last oil change for a vehicle",
    "properties": [
        {
            "name": "lastOilChangeDateTime",
            "type": "datetime",
            "nullable": "false"
        },
        {
            "name": "lastOilChangeMileage",
            "type": "double",
            "min": "0",
            "max": "999999999",
            "nullable": "false"
        },
        {
            "name": "brand",
            "type": "string",
            "max": "24",
            "nullable": "true"
        },
        {
            "name": "viscosity",
            "type": "string",
            "nullable": "true"
        }
    ]
}

架构定义

Field 说明
Name 窗体 {appDomain}_{schemaName} 的架构名称。 如果拥有 {appDomain}.com,可以直接使用 {appDomain}。 否则,必须使用反向 DNS 名称,将句点替换成下划线字符(即,如果域为“treyresearch.net”,请使用“net_treyresearch”)。
Description 架构的可读说明。 用于文档目的。 不出现在项上。
Properties 此架构中的属性定义。 请参阅下表。

属性定义

Field 说明
Name 数据中显示的属性名。 必须使用小写 camel 形式,只能包含字符 a-z 和 0-9。
Type 数据类型。 目前,OneDrive 仅支持 stringdatetimedouble
Min 允许的最小值(如果指定的话)。 对于字符串,此为长度限值。
Max 允许的最大值(如果指定的话)。 对于字符串,此为长度限值。 字符串长度必须小于 256 个字符。
Nullable 如果为 true,值是可选的。
Indexed 如果为 true,OneDrive 允许根据此属性的值进行查询、排序和筛选。

更新现有架构定义

可以更新架构定义,但不得破坏旧应用:

  • 不得删除现有属性
  • 所有新属性都必须为 nullable
  • 不得更改所有现有属性的 typeminmaxnullableindexed 值。