自定义 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 仅支持 string、datetime 和 double。 |
| Min | 允许的最小值(如果指定的话)。 对于字符串,此为长度限值。 |
| Max | 允许的最大值(如果指定的话)。 对于字符串,此为长度限值。 字符串长度必须小于 256 个字符。 |
| Nullable | 如果为 true,值是可选的。 |
| Indexed | 如果为 true,OneDrive 允许根据此属性的值进行查询、排序和筛选。 |
更新现有架构定义
可以更新架构定义,但不得破坏旧应用:
- 不得删除现有属性
- 所有新属性都必须为
nullable - 不得更改所有现有属性的
type、min、max、nullable和indexed值。