Créer openTypeExtension

  • Article

Espace de noms: microsoft.graph

Importante

Les API sous la version /beta dans Microsoft Graph sont susceptibles d’être modifiées. L’utilisation de ces API dans des applications de production n’est pas prise en charge. Pour déterminer si une API est disponible dans v1.0, utilisez le sélecteur Version .

Attention

Les applications existantes qui utilisent cette fonctionnalité avec baseTask ou baseTaskList doivent être mises à jour, car l’ensemble d’API de tâches basé sur ces ressources est déconseillé à compter du 31 mai 2022. Cet ensemble d'API cessera de renvoyer des données le 31 août 2022. Utilisez l’ensemble d’API basé sur todoTask.

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

En fonction de la ressource que vous créez l’extension dans et l’autorisation de type (délégué ou application) demandé, l’autorisation spécifiée dans le tableau suivant est moins requise privilégiée 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 Non pris en charge
todoTaskList Tasks.ReadWrite Tasks.ReadWrite Non pris en charge
utilisateur User.ReadWrite User.ReadWrite User.ReadWrite.All
baseTask (déconseillé) Tasks.ReadWrite Tasks.ReadWrite Non pris en charge
baseTaskList (déconseillé) Tasks.ReadWrite Tasks.ReadWrite Non pris en charge

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/{userId|userPrincipalName}/events
POST /users/{userId|userPrincipalName}/messages
POST /groups/{userId}/events
POST /groups/{userId}/threads/{threadId}/posts/{postId}/reply
POST /users/{userId|userPrincipalName}/contacts
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/todo/lists
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks
POST /users/{userId|userPrincipalName}/tasks/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 /administrativeunits/{administrativeUnitId}/extensions
POST /devices/{deviceId}/extensions
POST /users/{userId|userPrincipalName}/events/{eventId}/extensions
POST /groups/{groupId}/extensions
POST /groups/{groupId}/events/{eventId}/extensions
POST /groups/{groupId}/threads/{threadId}/posts/{postId}/extensions
POST /users/{userId|userPrincipalName}/messages/{messageId}/extensions
POST /organization/{organizationId}/extensions
POST /users/{userId|userPrincipalName}/contacts/{contactId}/extensions
POST /users/{userId|userPrincipalName}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/todo/lists/{listId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/tasks/{taskId}/extensions
POST /users/{userId|userPrincipalName}/tasks/lists/{listId}/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.

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 données personnalisées supplémentaires. 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 Chaîne unique

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. Consultez les rubriques relatives à la création de l’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.

Exemple

Demande 1

Le premier exemple 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/beta/me/messages
Content-Type: application/json

{
  "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 1

Voici la réponse pour le 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 demande stockée sous la forme de 3 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/beta/$metadata#Me/messages/$entity",
  "@odata.id": "https://graph.microsoft.com/beta/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/beta/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
    }
  ]
}

Demande 2

Le deuxième exemple 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 3 propriétés personnalisées dans la charge utile JSON : companyName, dealValue et expirationDate.
POST https://graph.microsoft.com/beta/me/messages/AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===/extensions
Content-Type: application/json

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

Réponse 2

Voici la réponse pour le 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/beta/$metadata#Me/messages('AAMkAGE1M2IyNGNmLTI5MTktNDUyZi1iOTVl===')/extensions/$entity",
    "@odata.type": "#microsoft.graph.openTypeExtension",
    "@odata.id": "https://graph.microsoft.com/beta/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"
}

Demande 3

Le troisième exemple 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 3 propriétés personnalisées dans la charge utile JSON : companyName, dealValue et expirationDate.
POST https://graph.microsoft.com/beta/groups/f5480dfd-7d77-4d0b-ba2e-3391953cc74a/events/AAMkADVl17IsAAA=/extensions
Content-type: application/json

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

Réponse 3

Voici la réponse pour la troisième demande.

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

{
    "@odata.context": "https://graph.microsoft.com/beta/$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"
}

Demande 4

Le quatrième exemple crée une extension dans un nouveau billet de groupe, à l’aide de la même action reply d’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 ».
  • Les données supplémentaires à stocker sous la forme de 3 propriétés personnalisées dans la charge utile JSON : companyName, expirationDate et le tableau de chaînes topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/threads/AAQkADJizZJpEWwqDHsEpV_KA==/posts/AAMkADJiUg96QZUkA-ICwMubAAC1heiSAAA=/reply
Content-type: application/json

{
  "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 4

Voici la réponse pour le quatrième exemple. 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

Demande 5

Le cinquième exemple 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 ».
  • Les données supplémentaires à stocker sous la forme de 3 propriétés personnalisées dans la charge utile JSON : companyName, expirationDate et le tableau de chaînes topPicks.
POST https://graph.microsoft.com/beta/groups/37df2ff0-0de0-4c33-8aee-75289364aef6/conversations
Content-type: application/json

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

Voici la réponse pour le cinquième exemple qui contient la nouvelle conversation et l’ID d’un 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/beta/$metadata#groups('37df2ff0-0de0-4c33-8aee-75289364aef6')/conversations/$entity",
    "id": "AAQkADJToRlbJ5Mg7TFM7H-j3Y=",
    "threads": [
        {
            "id": "AAQkADJDtMUzsf_PdhAAswJOhGVsnkyDtMUzsf_Pdg=="
        }
    ]
}