Erstellen und Aktualisieren von Optionen (Optionseinstellungen) über die Web-API

Artikel
08/24/2023

Normalerweise verwenden Sie globale Optionssätze zum Festlegen von Tabellenspalten, sodass verschiedene Spalten denselben Satz von Optionen verwenden können, die an einem Speicherort verwaltet werden. Anders als lokale Optionssätze, die nur für eine bestimmte Spalte definiert sind, können Sie globale Optionssätze wiederverwenden. Diese Werte werden auch in Anfrageparametern verwendet, ähnlich wie bei einer Aufzählung.

Hinweis

Sie können einen vorhandenen verwalteten Optionssatz nur dann ändern, wenn Sie der Herausgeber sind. Um eine Änderung wie beispielsweise eine Option zum Umbenennen oder zum Löschen an diesen Optionssätzen vorzunehmen, muss ein Upgrade für die Lösung durchgeführt werden, die den Optionssatz hinzugefügt hat. Weitere Informationen: Upgrade oder Update einer Lösung.

Wenn Sie ein globales Optionsset mit einer POST-Abfrage an [Organization URI]/api/data/v9.2/GlobalOptionSetDefinitions definieren, empfehlen wir, dass Sie das System einen Wert zuweisen lassen. Lassen Sie das System den Wert zuweisen, indem Sie einen null Wert übergeben, wenn Sie die neue OptionMetadata-Instanz erstellen. Wenn Sie eine Option definieren, enthält sie ein Präfix für den Optionswert, das spezifisch für den Kontext des Publisher-Sets für die Lösung ist, in der das Optionsset erstellt wird. Dieses Präfix verringert die Wahrscheinlichkeit, dass doppelte Optionssätze für ein verwaltete Lösung und in allen Optionssätzen erstellt werden, die in Umgebungen definiert sind, in denen Ihr verwaltete Lösung installiert ist. Weitere Informationen finden Sie unter Zusammenführung von Optionssatz-Optionen.

Nachrichten

Die folgende Tabelle enthält die Meldungen, die Sie mit globalen Optionssätzen verwenden können.

Nachricht	Web-API-Vorgang
`CreateOptionSet`	Verwenden Sie `POST`-Anfragen an [Organisations-URI]`/api/data/v9.2/GlobalOptionSetDefinitions`.
`DeleteOptionSet`	Verwenden Sie `DELETE`-Anfragen an [Organisations-URI]`/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>')`.
`RetrieveAllOptionSets`	Verwenden Sie `GET`-Anfragen an [Organisations-URI]`/api/data/v9.2/GlobalOptionSetDefinitions`.
`RetrieveOptionSet`	Verwenden Sie `GET`-Anfragen an [Organisations-URI]`/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>')`.

Die folgende Tabelle enthält die Meldungen, die Sie mit lokalen und globalen Optionssätzen verwenden können.

Nachricht	Web-API-Vorgang
`DeleteOptionValue` Löscht einen der Werte in einem globalen Optionssatz.	DeleteOptionValue Aktion Beispiel: Option Löschen
`InsertOptionValue` Fügt eine neue Option in einen globalen Optionssatz ein.	InsertOptionValue Aktion Beispiel: Optionen einfügen
`InsertStatusValue` Fügt eine neue Option in das globale Optionssatz ein, das in der `Status` Spalte verwendet wird.	InsertStatusValue Aktion Beispiel: Statuswert Einfügen
`OrderOption` Ändert die relative Reihenfolge der Optionen in einem Optionssatz.	OrderOption Aktion Beispiel: Sortiertoptionen
`UpdateOptionSet`	Verwenden Sie eine `PUT`-Anfrage mit einem OptionSetMetadataBase EntityType zu [Organisation URI]`/api/data/v9.2/GlobalOptionSetDefinitions(`Metadatenid`)` Nur die durch `OptionSetMetadataBase` definierten Eigenschaften können aktualisiert werden. Diese Eigenschaften enthalten nicht die Optionen. Verwenden Sie andere Aktionen, um Änderungen an Optionen vorzunehmen.
`UpdateOptionValue` Aktualisiert eine Option in einem Optionssatz.	Aktion UpdateOptionValue Beispiel: Optionen aktualisieren
`UpdateStateValue` Fügt eine neue Option in den globalen Optionssatz ein, der in der `Status` Spalte verwendet wird.	Aktion UpdateStateValue

Beispiele

Erstellen eines globalen Optionssatzes
Erstellen einer Spalte mit einem globalen Optionssatz
Optionen einfügen
Optionen aktualisieren
Anordnen von Optionen
Option löschen
Statuswert einfügen

Erstellen eines globalen Optionssatzes

Im folgenden Beispiel werden diese Eigenschaften verwendet, um eine globale Auswahl zu erstellen.

OptionSetMetadata Eigenschaften	Werte
`Name`	`sample_colors`
`DisplayName`	Farben
`Description`	Farbauswahl
`OptionSetType`	`Picklist`
`Options`	Wert: `727000000`, Label:Red Wert: `727000001`, Label:Yellow Wert: `727000002`, Label:Green

Das folgende Beispiel erstellt eine globale Auswahl unter Verwendung der Eigenschaften.

Die URI für die globale Auswahl wird in der Antwort zurückgegeben. Sie können auch auf diese globale Auswahl mit dem Namen GlobalOptionSetDefinitions(Name='sample_colors') verweisen.

Anforderung:

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

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/GlobalOptionSetDefinitions(1d733907-4d05-ee11-8f6e-000d3a993550)

Erstellung einer Auswahlspalte unter Verwendung eines globalen Optionssatzes

Im folgenden Beispiel werden diese Eigenschaften verwendet, um eine Spalte mit einer globalen Auswahl zu erstellen.

Eigenschaften von Attributen	Werte
`SchemaName`	`sample_Colors`
`DisplayName`	Farbbeispiele
`Description`	Attribut Globale Auswahlliste Farben
`RequiredLevel`	`None`
`GlobalOptionSet`	Diese Navigationseigenschaft mit einem Wert muss mit der Syntax `@odata.bind` und einem Verweis auf die globale Auswahl festgelegt werden. Dieses Beispiel verwendet die `MetadataId` als Schlüssel, könnte aber auch den alternativen Schlüssel mit `Name` verwenden: `GlobalOptionSetDefinitions(Name='sample_colors')`

Im folgenden Beispiel wird mithilfe der Eigenschaften eine lokale Spalte erstellt und zur Tabelle sample_bankaccount hinzugefügt.

Der URI für das Attribut wird in der Antwort zurückgegeben.

Anforderung:

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

Antwort:

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)

Optionen zum Einfügen

Das folgende Beispiel verwendet die InsertOptionValue Aktion, um eine neue Option mit dem Wert 727000005 und dem Label Echo zu der lokalen Auswahlspalte hinzuzufügen, die mit Erstelle eine Auswahlspalte erstellt wurde.

Anforderung:

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

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0

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

Optionen aktualisieren

Um einzelne Optionen zu aktualisieren, müssen Sie die UpdateOptionValue Aktion verwenden. Das folgende Beispiel aktualisiert die TrueOption aus dem Beispiel für die boolesche Spalte in Erstelle eine boolesche Spalte und ändert das Label, sodass es Up statt True lautet. Da dies ein „lokaler“ Optionssatz ist, verwendet er AttributeLogicalName und EntityLogicalName. Verwenden Sie für einen globalen Optionssatz stattdessen den Parameter OptionSetName.

Anforderung:

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
}

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Anordnen von Optionen

Das folgende Beispiel zeigt, wie Sie die Optionen eines lokalen OptionSets mit der OrderOption Aktion neu anordnen. Die Eigenschaft Value enthält die Werte der Option in der gewünschten Reihenfolge.

Um diese Funktion mit einem globalen Optionssatz zu verwenden, geben Sie den Parameter OptionSetName anstelle von EntityLogicalName und AttributeLogicalName an.

Der Parameter SolutionUniqueName wendet die Änderungen als Teil der angegebenen Lösung an.

Anforderung:

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

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Option Löschen

Das folgende Beispiel zeigt, wie Sie eine Option für eine lokale Spalte mit der DeleteOptionValue Aktion löschen können.

Um diese Funktion mit einem globalen Optionssatz zu verwenden, geben Sie den Parameter OptionSetName anstelle von EntityLogicalName und AttributeLogicalName an.

Der Parameter SolutionUniqueName wendet die Änderungen als Teil der angegebenen Lösung an.

Anforderung:

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
}

Antwort:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Statuswert einfügen

Das folgende Beispiel zeigt, wie Sie mit der InsertStatusValue Action eine Option zu einer Statusspalte hinzufügen können.

Verwenden Sie den Parameter StateCode, um anzugeben, für welche StateCode-Option der Statuswert gilt. Der Parameter SolutionUniqueName wendet die Änderungen als Teil der angegebenen Lösung an.

Die Eigenschaft NewOptionValue, die vom InsertStatusValueResponse ComplexType zurückgegeben wird, enthält den der Option zugewiesenen Wert.

Anforderung:

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

Antwort:

HTTP/1.1 200 OK
OData-Version: 4.0

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

Siehe auch

Passen Sie die Auswahl an
Erstellen und Bearbeiten globaler Auswahlmöglichkeiten – Übersicht
Eine Auswahl erstellen

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).

Freigeben über

Erstellen und Aktualisieren von Optionen (Optionseinstellungen) über die Web-API

Nachrichten

Beispiele

Erstellen eines globalen Optionssatzes

Erstellung einer Auswahlspalte unter Verwendung eines globalen Optionssatzes

Optionen zum Einfügen

Optionen aktualisieren

Anordnen von Optionen

Option Löschen

Statuswert einfügen

Siehe auch

Zusätzliche Ressourcen