Partager via


Créer une extension ouverte

Espace de noms: microsoft.graph

Créez une extension d’ouverture (objet openTypeExtension) et ajoutez des propriétés personnalisées dans une instance nouvelle ou existante d’une ressource. Vous pouvez créer une extension ouverteouverte dans une instance de ressource et y stocker des données personnalisées dans la même opération, à l’exception de ressources spécifiques.

Le tableau de la section Autorisations répertorie les ressources qui prennent en charge les extensions ouvertes.

Remarque : si vous créez des extensions ouvertes sur ressources Outlook, voirconsidérations relatives à Outlook spécifiques dans type de ressource openTypeExtension.

Cette API est disponible dans les déploiements de cloud national suivants.

Service global Gouvernement des États-Unis L4 Us Government L5 (DOD) Chine gérée par 21Vianet

Autorisations

Selon la ressource que vous créez, l’extension et le type d’autorisation (délégué ou application) demandé, l’autorisation spécifiée dans le tableau suivant est la moins privilégiée requise pour appeler cette API. Pour en savoir plus, notamment sur les Mesures de prudence avant de choisir des autorisations plus privilégiées, recherchez ces autorisations dans Autorisations.

Ressource prise en charge Déléguée (compte professionnel ou scolaire) Déléguée (compte Microsoft personnel) Application
appareil Directory.AccessAsUser.All Non pris en charge Device.ReadWrite.All
event Calendars.ReadWrite Calendars.ReadWrite Calendars.ReadWrite
group Group.ReadWrite.All Non pris en charge Group.ReadWrite.All
group event Group.ReadWrite.All Non pris en charge Non pris en charge
group post Group.ReadWrite.All Non pris en charge Group.ReadWrite.All
message Mail.ReadWrite Mail.ReadWrite Mail.ReadWrite
organization Organization.ReadWrite.All Non pris en charge Organization.ReadWrite.All
personal contact Contacts.ReadWrite Contacts.ReadWrite Contacts.ReadWrite
todoTask Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Tasks.ReadWrite.All
user User.ReadWrite User.ReadWrite User.ReadWrite.All

Requête HTTP

Créer une extension dans une nouvelle instance de la ressource

Utilisez la même requête REST qui vous permet de créer l’instance.

POST /users/{id|userPrincipalName}/events
POST /users/{id|userPrincipalName}/messages
POST /groups/{id}/events
POST /groups/{id}/threads/{id}/posts/{id}/reply
POST /users/{id|userPrincipalName}/contacts
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks
POST /users/{id|userPrincipalName}/todo/lists

Remarque: La syntaxe ci-dessus présente quelques techniques courantes pour créer les instances de ressource prises en charge. Toutes les autres syntaxes POST qui vous permettent de créer ces instances de ressource prennent en charge la création des extensions d’ouverture dans celles-ci de façon similaire.

Reportez-vous à la section Corps de la demande concernant l’inclusion des propriétés de la nouvelle instance de la ressource et de l’extension dans le corps de la demande.

Créer une extension dans une instance de la ressource existants

Identifiez l’instance de la ressource dans la demande et effectuez unePOST sur la propriété de navigation extensions.

POST /devices/{id}/extensions
POST /users/{id|userPrincipalName}/events/{id}/extensions
POST /groups/{id}/extensions
POST /groups/{id}/events/{id}/extensions
POST /groups/{id}/threads/{id}/posts/{id}/extensions
POST /users/{id|userPrincipalName}/messages/{id}/extensions
POST /organization/{id}/extensions
POST /users/{id|userPrincipalName}/contacts/{id}/extensions
POST /users/{id|userPrincipalName}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/tasks/{id}/extensions
POST /users/{id|userPrincipalName}/todo/lists/{id}/extensions

Remarque: La syntaxe ci-dessus présente quelques techniques courantes d’identification d’une instance de ressource, afin de créer une extension dans celle-ci. Toutes les autres syntaxes qui vous permettent d’identifier ces instances de ressource prennent en charge la création des extensions d’ouverture dans celles-ci de façon similaire.

Reportez-vous à la section Corps de la demande concernant l’inclusion de l’extension dans le corps de la demande.

Paramètres du chemin d’accès

Paramètre Type Description
id string Un identificateur unique pour un objet dans la collection correspondante. Obligatoire.

En-têtes de demande

Nom Valeur
Autorisation Porteur {token}. Obligatoire. En savoir plus sur l’authentification et l’autorisation.
Content-Type application/json

Corps de la demande

Fournissez un corps JSON d’un openTypeExtension, avec les paires nom-valeur requises suivantes, et toutes les autres données personnalisées. Les données de la charge utile JSON peuvent être des types primitifs ou des tableaux de types primitifs.

Nom Valeur
@odata.type microsoft.graph.openTypeExtension
extensionName % unique_string %

Lorsque vous créez une extension dans une nouvelle instance de la ressource, outre le nouvel objet openTypeExtension, fournissez une représentation JSON des propriétés applicables pour créer cette instance de la ressource.

Réponse

Code de réponse

En fonction de l’opération, le code de réponse peut être 201 Created ou 202 Accepted.

Lorsque vous créez une extension à l’aide de la même opération qui vous permet de créer une instance de la ressource, l’opération renvoie le même code réponse qu’elle renvoie lorsque vous utilisez l’opération pour créer l’instance de la ressource sans l’extension. Reportez-vous aux articles correspondants pour créer le instance, comme indiqué ci-dessus.

Corps de la réponse

Scénario Ressource Corps de la réponse
Création d’une extension lors de la création explicite d’une nouvelle instance de la ressource contact, event, message Inclut la nouvelle instance développée avec l’objet openTypeExtension.
Création d’une extension lors de la création implicite d’une instance de la ressource post La réponse inclut uniquement un code de réponse, et n’a pas de corps.
Création d’une extension dans une instance de la ressource existante Toutes les ressources prises en charge Inclut l’objet openTypeExtension.

Exemples

Exemple 1 : Créer un message et une extension dans le même appel

Demande

L’exemple suivant crée un message et une extension dans le même appel. Le corps de la demande inclut les éléments suivants :

  • Les propriétés subject, body et toRecipients par défaut d’un nouveau message.

  • Pour l’extension :

    • Le type microsoft.graph.openTypeExtension.
    • Le nom de l’extension « Com.Contoso.Referral ».
    • Les données supplémentaires à stocker sous la forme de trois propriétés personnalisées dans la charge utile JSON : companyName, expirationDate et dealValue.
POST https://graph.microsoft.com/v1.0/me/messages

{
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "You should be proud!"
  },
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com"
      }
    }
  ],
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Réponse

L’exemple suivant montre la réponse du premier exemple. Le corps de la réponse inclut les propriétés du nouveau message et les informations suivantes sur la nouvelle extension :

  • La propriété id avec le nom complet de microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • La propriété par défaut extensionName spécifiée dans la demande.
  • Les données personnalisées spécifiées dans la requête sont stockées sous la forme de trois propriétés personnalisées.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

HTTP/1.1 201 Created
Content-type: application/json

{
  "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')",
  "@odata.etag": "W/\"CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj\"",
  "id": "AAMkAGEbs88AAB84uLuAAA=",
  "createdDateTime": "2015-10-30T03:03:43Z",
  "lastModifiedDateTime": "2015-10-30T03:03:43Z",
  "changeKey": "CQAAABYAAACY4MQpaFz9SbqUDe4+bs88AAB88LOj",
  "categories": [ ],
  "receivedDateTime": "2015-10-30T03:03:43Z",
  "sentDateTime": "2015-10-30T03:03:43Z",
  "hasAttachments": false,
  "subject": "Annual review",
  "body": {
    "contentType": "HTML",
    "content": "<html>\r\n<head>\r\n<meta http-equiv=\"Content-Type\" content=\"text/html; charset=utf-8\">\r
\n<meta content=\"text/html; charset=us-ascii\">\r\n</head>\r\n<body>\r\nYou should be proud!\r\n</body>\r
\n</html>\r\n"
  },
  "bodyPreview": "You should be proud!",
  "importance": "Normal",
  "parentFolderId": "AQMkAGEwAAAIBDwAAAA==",
  "sender": null,
  "from": null,
  "toRecipients": [
    {
      "emailAddress": {
        "address": "rufus@contoso.com",
        "name": "John Doe"
      }
    }
  ],
  "ccRecipients": [ ],
  "bccRecipients": [ ],
  "replyTo": [ ],
  "conversationId": "AAQkAGEFGugh3SVdMzzc=",
  "isDeliveryReceiptRequested": false,
  "isReadReceiptRequested": false,
  "isRead": true,
  "isDraft": true,
  "webLink": "https://outlook.office.com/owa/?
ItemID=AAMkAGEbs88AAB84uLuAAA%3D&exvsurl=1&viewmodel=ReadMessageItem",
  "inferenceClassification": "Focused",
  "extensions": [
    {
      "@odata.type": "#microsoft.graph.openTypeExtension",
      "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df800e5@1717f226-49d1-4d0c-9d74-709fad664b77')/messages
('AAMkAGEbs88AAB84uLuAAA=')/extensions('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
      "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
      "extensionName": "Com.Contoso.Referral",
      "companyName": "Wingtip Toys",
      "expirationDate": "2015-12-30T11:00:00.000Z",
      "dealValue": 10000
    }
  ]
}

Exemple 2 : Créer une extension dans le message spécifié

Demande

L’exemple suivant crée une extension dans le message spécifié. Le corps de la demande inclut les informations suivantes sur l’extension :

  • Le type microsoft.graph.openTypeExtension.
  • Le nom de l’extension « Com.Contoso.Referral ».
  • Les données supplémentaires à stocker sous la forme de trois propriétés personnalisées dans la charge utile JSON : companyName, dealValue et expirationDate.
POST https://graph.microsoft.com/v1.0/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Referral",
  "companyName" : "Wingtip Toys",
  "dealValue" : 500050,
  "expirationDate" : "2015-12-03T10:00:00.000Z"
}

Réponse

L’exemple suivant montre la réponse du deuxième exemple. Le corps de la réponse inclut les informations suivantes sur la nouvelle extension :

  • La propriété par défaut extensionName.
  • La propriété id avec le nom complet de microsoft.graph.openTypeExtension.Com.Contoso.Referral.
  • Les données personnalisées à stocker.
HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/v1.0/users('ddfc984d-b826-40d7-b48b-57002df85e00@1717f226-49d1-4d0c-9d74-709fad6677b4')/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions
('microsoft.graph.openTypeExtension.Com.Contoso.Referral')",
    "extensionName": "Com.Contoso.Referral",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Referral",
    "companyName": "Wingtip Toys",
    "dealValue": 500050,
    "expirationDate": "2015-12-03T10:00:00.000Z"
}

Exemple 3 : Créer une extension dans l’événement de groupe spécifié

Demande

L’exemple suivant crée une extension dans l’événement de groupe spécifié. Le corps de la demande inclut les informations suivantes sur l’extension :

  • Le type microsoft.graph.openTypeExtension.
  • Le nom de l’extension « Com.Contoso.Deal ».
  • Les données supplémentaires à stocker sous la forme de trois propriétés personnalisées dans la charge utile JSON : companyName, dealValue et expirationDate.
POST https://graph.microsoft.com/v1.0/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions

{
  "@odata.type" : "microsoft.graph.openTypeExtension",
  "extensionName" : "Com.Contoso.Deal",
  "companyName" : "Alpine Skis",
  "dealValue" : 1010100,
  "expirationDate" : "2015-07-03T13:04:00.000Z"
}

Réponse

L’exemple suivant illustre la réponse.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('f5480dfd-7d77-4d0b-ba2e-3391953cc74a')/events('AAMkADVl7IsAAA%3D')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "id": "microsoft.graph.openTypeExtension.Com.Contoso.Deal",
    "extensionName": "Com.Contoso.Deal",
    "companyName": "Alpine Skis",
    "dealValue": 1010100,
    "expirationDate": "2015-07-03T13:04:00Z"
}

Exemple 4 : Créer une extension dans un nouveau billet de groupe

Demande

L’exemple suivant crée une extension dans un nouveau billet de groupe, en utilisant le même appel d’action de réponse à un billet de groupe existant. L’action reply crée un nouveau billet, et une nouvelle extension incorporée dans le billet. Le corps de la demande inclut la propriété post, qui à son tour contient le corps du nouveau billet, ainsi que les informations suivantes sur la nouvelle extension :

  • Le type microsoft.graph.openTypeExtension.
  • Le nom de l’extension « Com.Contoso.HR ».
  • Données supplémentaires à stocker en tant que trois propriétés personnalisées dans la charge utile JSON : companyName, expirationDateet le tableau de chaînes topPicks.
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply

{
  "post": {
    "body": {
      "contentType": "html",
      "content": "<html><body><div><div><div><div>When and where? </div></div></div></div></body></html>"
    },
  "extensions": [
    {
      "@odata.type": "microsoft.graph.openTypeExtension",
      "extensionName": "Com.Contoso.HR",
      "companyName": "Contoso",
      "expirationDate": "2015-07-03T13:04:00.000Z",
      "topPicks": [
        "Employees only",
        "Add spouse or guest",
        "Add family"
      ]
    }
  ]
  }
}

Réponse

L’exemple suivant illustre la réponse. La création réussie d’une extension dans un nouveau billet de groupe génère uniquement le code de réponse HTTP 202.

HTTP/1.1 202 Accepted
Content-type: text/plain
Content-Length: 0

Exemple 5 : Créer une extension dans un nouveau billet de groupe à l’aide de l’opération POST

Demande 5

L’exemple suivant crée une extension dans un nouveau billet de groupe à l’aide de la même opération POST pour créer une conversation. L’opération POST crée une nouvelle conversation, un nouveau thread, un nouveau billet, et une nouvelle extension incorporée dans le billet. Le corps de la demande inclut les propriétés Topic et Threads, et un objet enfant post pour la nouvelle conversation. L’objet post contient à son tour le corps du nouveau billet et les informations suivantes sur l’extension :

  • Le type microsoft.graph.openTypeExtension.
  • Le nom de l’extension « Com.Contoso.HR ».
  • Données supplémentaires à stocker en tant que trois propriétés personnalisées dans la charge utile JSON : companyName, expirationDateet le tableau de chaînes topPicks.
POST https://graph.microsoft.com/v1.0/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations

{
  "Topic": "Does anyone have a second?",
  "Threads": [
    {
      "Posts": [
        {
          "Body": {
            "ContentType": "HTML",
            "Content": "This is urgent!"
          },
          "Extensions": [
            {
              "@odata.type": "microsoft.graph.openTypeExtension",
              "extensionName": "Com.Contoso.Benefits",
              "companyName": "Contoso",
              "expirationDate": "2016-08-03T11:00:00.000Z",
              "topPicks": [
                "Employees only",
                "Add spouse or guest",
                "Add family"
              ]
            }
          ]
        }
      ]
    }
  ]
}

Réponse 5

L’exemple suivant montre la réponse, qui contient la nouvelle conversation et un ID de thread. Ce nouveau thread contient un billet créé automatiquement, qui contient à son tour la nouvelle extension.

Remarque : l’objet de réponse affiché ci-après peut être raccourci pour plus de lisibilité.

Pour obtenir la nouvelle extension, commencez par obtenir toutes les publications de ce thread, et au départ, il ne devrait y en avoir qu’une seule. Ensuite, appliquez l’ID de publication et le nom Com.Contoso.Benefits de l’extension pour obtenir l’extension.

HTTP/1.1 201 Created
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}