Créer et mettre à jour les options (groupes d’options) à l’aide de l’API web

  • Article

En règle générale, vous utilisez les groupes d’options global pour définir des colonnes de table afin que différentes colonnes puissent partager le même ensemble d’options, qui sont conservées au même endroit. Contrairement aux groupes d’options local qui ne sont définis que pour une colonne spécifique, vous pouvez réutiliser les groupes d’options globaux. Ces valeurs sont également utilisées dans les paramètres de demande de façon similaire à une énumération.

Notes

Vous ne pouvez modifier un groupe d’options géré existant que si vous êtes l’éditeur. Afin d’apporter une modification, comme l’option de changement de nom ou l’option de suppression, sur ces groupes d’options, il est nécessaire de mettre à niveau la solution qui a ajouté le groupe d’options. Plus d’informations : Mettre à niveau ou mettre à jour une solution

Lorsque vous définissez un groupe d’options global à l’aide d’une requête POST vers [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 de groupes d’options en double pour un solution gérée et dans tous les groupes d’options définis dans les environnements où votre solution gérée est installé. Pour plus d’informations, voir Fusionner les options d’un groupe d’options.

Messages

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 les groupes d’options globaux et locaux.

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

Examples

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 vous référer à ce choix global en utilisant le 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(1d733907-4d05-ee11-8f6e-000d3a993550)

Créer une colonne de choix à l’aide d’un groupe d’options global

L’exemple suivant utilise ces propriétés pour créer une colonne de choix local avec 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 Cette propriété de navigation à valeur unique doit être définie avec la syntaxe @odata.bind 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 table sample_bankaccount.

L’URI pour l’attribut est renvoyée dans la réponse.

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(1d733907-4d05-ee11-8f6e-000d3a993550)",
  "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(25733907-4d05-ee11-8f6e-000d3a993550)

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, vous devez utiliser l’action UpdateOptionValue. L’exemple suivant met à jour la TrueOption de l’exemple de colonne booléenne dans Créer une colonne booléenne et modifie l’étiquette de sorte qu’elle soit Up plutôt que True. Comme il s’agit d’un groupe d’options "local", il 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 d’un groupe d’options global en utilisant l’action OrderOption. La propriété Value contient les valeurs de l’option dans l’ordre souhaité.

Pour l’utiliser avec un groupe d’options global, spécifiez le paramètre OptionSetName plutôt que EntityLogicalName et AttributeLogicalName.

Le paramètre SolutionUniqueName applique 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 pour une colonne de choix locaux à l’aide de l’action DeleteOptionValue.

Pour l’utiliser avec un groupe d’options global, spécifiez le paramètre OptionSetName plutôt que EntityLogicalName et AttributeLogicalName.

Le paramètre SolutionUniqueName applique 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 de statut à 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

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).