Créer et mettre à jour des choix (ensembles d’options) à l’aide de l’API web

Cet article explique comment créer et mettre à jour des choix Microsoft Dataverse (ensembles d’options) à l’aide de l’API Web, afin de conserver des valeurs d’option cohérentes entre les colonnes de table. Utilisez des choix globaux lorsque plusieurs colonnes ont besoin des mêmes options et utilisez des choix locaux pour une colonne spécifique.

Nonte

Vous ne pouvez modifier qu’un jeu d’options managées existant si vous êtes l’éditeur. Pour renommer ou supprimer une option dans ces jeux d’options, vous devez mettre à niveau la solution qui a ajouté le jeu d’options. Pour plus d’informations, consultez Mettre à niveau ou mettre à jour une solution.

Lorsque vous définissez une option globale définie à l’aide d’une POST requête sur [URI de l’organisation],/api/data/v9.2/GlobalOptionSetDefinitions nous vous recommandons de laisser le système attribuer une valeur. Laissez le système attribuer la valeur en transmettant une valeur null lorsque vous créez l’instance OptionMetadata. Lorsque vous définissez une option, elle contient un préfixe de valeur d’option spécifique au contexte du groupe d’éditeurs pour la solution dans laquelle le groupe d’options est créé. Ce préfixe permet de réduire le risque de création d’ensembles d’options en double pour une solution managée, et dans tous les ensembles d’options que vous définissez dans les environnements où votre solution managée est installée. Pour plus d’informations, voir Fusionner les options d’un groupe d’options.

Opérations d’API web pour les choix

Le tableau suivant répertorie les messages que vous pouvez utiliser avec les groupes d’options globaux.

Message Opération de l’API Web
CreateOptionSet Utilisez la demande POST sur [URI de l’organisation]/api/data/v9.2/GlobalOptionSetDefinitions.
DeleteOptionSet Utilisez la demande DELETE sur [URI de l’organisation]/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>').
RetrieveAllOptionSets Utilisez la demande GET sur [URI de l’organisation]/api/data/v9.2/GlobalOptionSetDefinitions.
RetrieveOptionSet Utilisez la demande GET sur [URI de l’organisation]/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>').

Le tableau suivant répertorie les messages que vous pouvez utiliser avec des ensembles d’options locaux et globaux.

Message Opération de l’API Web
DeleteOptionValue
Supprime une des valeurs dans un groupe d’options global.		 Action DeleteOptionValue
Exemple : Option Supprimer
InsertOptionValue
Insère une nouvelle option dans un groupe d’options global.		 Action InsertOptionValue
Exemple : Options Insérer
InsertStatusValue
Insère une nouvelle option dans le groupe d’options global utilisé dans la colonne Status.		 Action InsertStatusValue
Exemple : Valeur du statut Insérer
OrderOption
Modifie l’ordre relatif des options dans un groupe d’options.		 Action OrderOption
Exemple : Options d’ordre
UpdateOptionSet Utilisez la demande PUT avec un OptionSetMetadataBase EntityType vers [URI de l’organisation]/api/data/v9.2/GlobalOptionSetDefinitions(metadataid)
Seules les propriétés définies par OptionSetMetadataBase peuvent être mises à jour. Ces propriétés n’incluent pas les options. Utilisez d’autres actions pour modifier les options.
UpdateOptionValue
Met à jour une option dans un groupe d’options.		 Action UpdateOptionValue
Exemple : Options Mettre à jour
UpdateStateValue
Insère une nouvelle option dans le groupe d’options utilisé dans la colonne Status.		 Action UpdateStateValue

Exemples d’API web pour les choix

Créer un groupe d’options général

L’exemple suivant utilise ces propriétés pour créer un choix global.

Propriétés OptionSetMetadata Valeurs
Name sample_colors
DisplayName Couleurs
Description Choix de la couleur
OptionSetType Picklist
Options valeur : 727000000, étiquette : Rouge
valeur :727000001, étiquette :Jaune
valeur :727000002, étiquette :Vert

L’exemple suivant crée un choix global avec ces propriétés.

L’URI pour le choix global est renvoyée dans la réponse. Vous pouvez également faire référence à ce choix global à l’aide du nom : GlobalOptionSetDefinitions(Name='sample_colors').

Demande :

POST [Organization Uri]/api/data/v9.2/GlobalOptionSetDefinitions
MSCRM.SolutionUniqueName: examplesolution
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 2769

{
  "@odata.type": "Microsoft.Dynamics.CRM.OptionSetMetadata",
  "Options": [
    {
      "Value": 727000000,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Red",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Red",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    },
    {
      "Value": 727000001,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Yellow",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Yellow",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    },
    {
      "Value": 727000002,
      "Label": {
        "@odata.type": "Microsoft.Dynamics.CRM.Label",
        "LocalizedLabels": [
          {
            "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
            "Label": "Green",
            "LanguageCode": 1033,
            "IsManaged": false
          }
        ],
        "UserLocalizedLabel": {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Green",
          "LanguageCode": 1033,
          "IsManaged": false
        }
      }
    }
  ],
  "Description": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Color Choice",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Color Choice",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "DisplayName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Colors",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Colors",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "Name": "sample_colors",
  "OptionSetType": "Picklist"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/GlobalOptionSetDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)

Créer une colonne de choix à l’aide d’un ensemble d’options globales

L’exemple suivant utilise ces propriétés pour créer une colonne de choix à l’aide d’un choix global.

Propriétés de l’attribut Liste de sélection Valeurs
SchemaName sample_Colors
DisplayName Exemple de couleurs
Description Attribut de liste de sélection global de couleurs
RequiredLevel None
GlobalOptionSet Définissez cette propriété de navigation à valeur unique à l’aide de la @odata.bind syntaxe avec une référence au choix global. Cet exemple utilise le MetadataId comme clé, mais il pourrait également utiliser le clé secondaire avec Name : GlobalOptionSetDefinitions(Name='sample_colors')

L’exemple suivant crée une colonne locale à l’aide des propriétés et l’ajoute à la sample_bankaccount table.

La réponse retourne l’URI de l’attribut.

Demande :

POST [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes
MSCRM.SolutionUniqueName: examplesolution
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 1465

{
  "@odata.type": "Microsoft.Dynamics.CRM.PicklistAttributeMetadata",
  "AttributeType": "Picklist",
  "AttributeTypeName": {
    "Value": "PicklistType"
  },
  "SourceTypeMask": 0,
  "GlobalOptionSet@odata.bind": "/GlobalOptionSetDefinitions(00aa00aa-bb11-cc22-dd33-44ee44ee44ee)",
  "Description": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Colors Global Picklist Attribute",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Colors Global Picklist Attribute",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "DisplayName": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Sample Colors",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Sample Colors",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "RequiredLevel": {
    "Value": "None",
    "CanBeChanged": false,
    "ManagedPropertyLogicalName": "canmodifyrequirementlevelsettings"
  },
  "SchemaName": "sample_Colors"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/EntityDefinitions(LogicalName='sample_bankaccount')/Attributes(11bb11bb-cc22-dd33-ee44-55ff55ff55ff)

Options Insérer

L’exemple suivant utilise l’action InsertOptionValue pour ajouter une nouvelle option avec la valeur 727000005 et l’étiquette Echo à la colonne de choix locale créée par Créer une colonne de choix.

Demande :

POST [Organization Uri]/api/data/v9.2/InsertOptionValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 612

{
  "AttributeLogicalName": "sample_choice",
  "EntityLogicalName": "sample_bankaccount",
  "Value": 727000005,
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Echo",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Echo",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "SolutionUniqueName": "examplesolution"
}

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InsertOptionValueResponse",
  "NewOptionValue": 727000005
}

Options de mise à jour

Pour mettre à jour des options individuelles, utilisez l’action UpdateOptionValue. L’exemple suivant met à jour l’exemple TrueOption de colonne booléenne dans Créer une colonne booléenne et modifie l’étiquette au Up lieu de True. Étant donné que cet ensemble d’options est local, l’exemple utilise AttributeLogicalName et EntityLogicalName. Pour un groupe d’options global, utilisez le paramètre OptionSetName à la place.

Demande :

POST [Organization Uri]/api/data/v9.2/UpdateOptionValue HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "AttributeLogicalName": "new_boolean",
  "EntityLogicalName": "new_bankaccount",
  "Value": 1,
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Up",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Up",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "MergeLabels": true
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Trier les options

L’exemple suivant montre comment réorganiser les options dans une option locale définie à l’aide de l’action OrderOption. La propriété Value contient les valeurs de l’option dans l’ordre souhaité.

Pour utiliser cette action avec un ensemble d’options globales, spécifiez le OptionSetName paramètre au lieu de EntityLogicalName et AttributeLogicalName.

Utilisez le SolutionUniqueName paramètre pour appliquer les modifications dans le cadre de la solution spécifiée.

Demande :

POST [Organization Uri]/api/data/v9.2/OrderOption
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 253

{
  "EntityLogicalName": "sample_bankaccount",
  "AttributeLogicalName": "sample_choice",
  "Values": [
    727000002,
    727000000,
    727000003,
    727000001,
    727000005,
    727000004
  ],
  "SolutionUniqueName": "examplesolution"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Option Supprimer

L’exemple suivant montre comment supprimer une option dans une colonne de choix local à l’aide de l’action DeleteOptionValue.

Pour utiliser cette action avec un ensemble d’options globales, spécifiez le OptionSetName paramètre au lieu de EntityLogicalName et AttributeLogicalName.

Utilisez le SolutionUniqueName paramètre pour appliquer les modifications dans le cadre de la solution spécifiée.

Demande :

POST [Organization Uri]/api/data/v9.2/DeleteOptionValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 116

{
  "AttributeLogicalName": "sample_choice",
  "EntityLogicalName": "sample_bankaccount",
  "Value": 727000004
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Valeur de statut Insérer

L’exemple suivant montre comment ajouter une option à une colonne d’état à l’aide de l’action InsertStatusValue.

Utilisez le paramètre StateCode pour spécifier à quelle option de code d’état la valeur d’état s’applique. Le paramètre SolutionUniqueName applique les modifications dans le cadre de la solution spécifiée.

La propriété NewOptionValue renvoyée par InsertStatusValueResponse ComplexType contient la valeur attribuée à l’option.

Demande :

POST [Organization Uri]/api/data/v9.2/InsertStatusValue
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json
Content-Type: application/json; charset=utf-8
Content-Length: 609

{
  "AttributeLogicalName": "statuscode",
  "EntityLogicalName": "sample_bankaccount",
  "Label": {
    "@odata.type": "Microsoft.Dynamics.CRM.Label",
    "LocalizedLabels": [
      {
        "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
        "Label": "Frozen",
        "LanguageCode": 1033,
        "IsManaged": false
      }
    ],
    "UserLocalizedLabel": {
      "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
      "Label": "Frozen",
      "LanguageCode": 1033,
      "IsManaged": false
    }
  },
  "StateCode": 1,
  "SolutionUniqueName": "examplesolution"
}

Réponse :

HTTP/1.1 200 OK
OData-Version: 4.0

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.InsertStatusValueResponse",
  "NewOptionValue": 727000000
}

Voir aussi

Personnaliser les options
Présentation de la création et de la modification d’un choix global
Créer un choix

  • Last updated on