Facettes Custom (version préliminaire)

Les facettes Custom vous permettent d’enregistrer vos métadonnées dans les éléments. Elles peuvent servir à effectuer le suivi de l’état personnalisé pour un élément, de conserver un lien dans un élément associé d’un autre système, ainsi que d’autres actions. Tout comme les facettes OneDrive, les facettes Custom suivent un schéma qui garantit que les données sont cohérentes et valides, même lorsqu’elles sont utilisées avec plusieurs applications.

Remarque : Les facettes Custom sont en mode d’aperçu et sont disponibles uniquement pour OneDrive Personnel à ce stade.

Lecture des facettes Custom

Pour afficher les facettes Custom sur un élément, vous devez répertorier les noms des facettes de manière explicite dans le select paramètre de requête. Bien que les facettes Custom s’affichent à côté des facettes standard, elles ne sont pas renvoyées sauf si elles sont incluses dans la déclaration select.

Exemple

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

Réponse

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

Écriture dans les facettes Custom

Les facettes Custom peuvent être fournies comme les facettes standard dans les appels create ou update. Vous pouvez fournir des facettes Custom et des facettes standard dans le même appel.

Exemple

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

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

Réponse

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

Enregistrement du schéma

Avant de pouvoir utiliser une nouvelle facette Custom, vous devez définir son schéma et l’enregistrer avec OneDrive. Pour enregistrer votre facette Custom, contactez le service Enregistrement de la facette OneDrive et fournissez votre client_id et la définition de schéma JSON.

Voici un exemple de définition de schéma.

{
    "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"
        }
    ]
}

Définition de schéma

Field	Description
Nom	Nom de schéma du formulaire {appDomain}_{schemaName}. Si vous êtes propriétaire de {appDomain}.com, vous pouvez utiliser tout simplement {appDomain}. Dans le cas contraire, vous devez utiliser votre nom DNS inverse, avec des traits de soulignement remplaçant les points (par ex., si votre domaine est « treyresearch.net », vous devez utiliser « net_treyresearch »).
Description	Description explicite du schéma. À des fins de documentation. N’apparaît pas dans l’élément.
Propriétés	Définitions des propriétés dans ce schéma. Consultez le tableau ci-dessous.

Définition de la propriété

Field	Description
Nom	Nom de la propriété, tel qu’il apparaît dans les données. Doit être « lowerCamelCased » et contenir uniquement les caractères a-z et 0-9.
Type	Type de données. Actuellement, OneDrive prend en charge uniquement string, datetime et double.
Min	Si spécifié, valeur minimale autorisée. Pour les chaînes, il s’agit de la longueur.
Max	Si spécifié, valeur maximale autorisée. Pour les chaînes, il s’agit de la longueur. Le nombre de caractères des chaînes doit être inférieur à 256.
Nullable	Si la valeur est true, la valeur est facultative.
Indexé	Si la valeur est true, OneDrive vous permet d’effectuer une requête, de trier et de filtrer selon la valeur de cette propriété.

Mise à jour d’une définition de schéma existante

Vous pouvez mettre à jour la définition d’un schéma, mais uniquement d’une manière qui ne rompt pas les anciennes applications :

• Les propriétés existantes ne peuvent pas être supprimées
• Toutes les nouvelles propriétés doivent être définies sur nullable
• Toutes les propriétés existantes doivent comporter les mêmes valeurs que les précédentes pour type, min, max, nullable et indexed.