Criar e atualizar opções (conjuntos de opções) usando a API Web

Este artigo explica como criar e atualizar Microsoft Dataverse opções (conjuntos de opções) usando a API Web, para que você possa manter valores de opção consistentes entre colunas de tabela. Use opções globais quando várias colunas precisarem das mesmas opções e usar opções locais para uma coluna específica.

Note

Você só poderá alterar um conjunto de opções gerenciadas existente se for o editor. Para renomear ou excluir uma opção nesses conjuntos de opções, você deve atualizar a solução que adicionou o conjunto de opções. Para obter mais informações, consulte Fazer upgrade ou atualizar uma solução.

Quando você define um conjunto de opções global usando uma POST solicitação para [URI da Organização]/api/data/v9.2/GlobalOptionSetDefinitions, recomendamos que você permita que o sistema atribua um valor. Permitir que o sistema atribua o valor passando um valor nulo ao criar a nova OptionMetadata instância. Quando você define uma opção, ela contém um prefixo de valor de opção específico ao contexto do conjunto de editores para a solução na qual o conjunto de opções é criado. Esse prefixo ajuda a reduzir a chance de criar conjuntos de opções duplicados para uma solução gerenciada e em qualquer conjunto de opções que você definir em ambientes em que sua solução gerenciada está instalada. Para obter mais informações, consulte as opções de conjunto de opções de mesclagem.

Operações de API Web para opções

A tabela a seguir lista as mensagens que você pode usar com conjuntos de opções globais.

Message	Operação da API Web
`CreateOptionSet`	Use `POST` a solicitação para [URI da organização]`/api/data/v9.2/GlobalOptionSetDefinitions`.
`DeleteOptionSet`	Use `DELETE` a solicitação para [URI da organização]`/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>')`.
`RetrieveAllOptionSets`	Use `GET` a solicitação para [URI da organização]`/api/data/v9.2/GlobalOptionSetDefinitions`.
`RetrieveOptionSet`	Use `GET` a solicitação para [URI da organização]`/api/data/v9.2/GlobalOptionSetDefinitions(Name='<name>')`.

A tabela a seguir lista as mensagens que você pode usar com conjuntos de opções locais e globais.

Message	Operação da API Web
`DeleteOptionValue` Exclui um dos valores em um conjunto de opções global.	Ação DeleteOptionValue Exemplo: opção Excluir
`InsertOptionValue` Insere uma nova opção em um conjunto de opções global.	Ação InsertOptionValue Exemplo: opções de inserção
`InsertStatusValue` Insere uma nova opção no conjunto de opções global usado na `Status` coluna.	Ação InsertStatusValue Exemplo: Inserir valor de status
`OrderOption` Altera a ordem relativa das opções em um conjunto de opções.	Ação OrderOption Exemplo: Opções de pedido
`UpdateOptionSet`	Usar `PUT` solicitação com um EntityType OptionSetMetadataBase para [URI da Organização]`/api/data/v9.2/GlobalOptionSetDefinitions(`metadados`)` Somente as propriedades definidas pelo `OptionSetMetadataBase` poderão ser atualizadas. Essas propriedades não incluem as opções. Use outras ações para fazer alterações nas opções.
`UpdateOptionValue` Atualiza uma opção em um conjunto de opções.	Ação UpdateOptionValue Exemplo: opções de atualização
`UpdateStateValue` Insere uma nova opção no conjunto de opções usado na `Status` coluna.	Ação UpdateStateValue

Exemplos de API Web para opções

Criar um conjunto de opções global
Criar uma coluna de escolha usando um conjunto de opções global
Opções de inserção
Opções de atualização
Opções de pedido
Opção Excluir
Inserir valor de status

Criar um conjunto de opções globais

O exemplo a seguir usa essas propriedades para criar uma escolha global.

Propriedades OptionSetMetadata	Values
`Name`	`sample_colors`
`DisplayName`	Cores
`Description`	Opção de cor
`OptionSetType`	`Picklist`
`Options`	value:`727000000`, label:Red value:`727000001`, label:Yellow value:`727000002`, label:Green

O exemplo a seguir cria a opção global usando as propriedades.

O URI para a escolha global é retornado na resposta. Você também pode se referir a essa escolha global usando o nome: GlobalOptionSetDefinitions(Name='sample_colors').

Solicitação:

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

Resposta:

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

Criar uma coluna de escolha usando um conjunto de opções global

O exemplo a seguir usa essas propriedades para criar uma coluna de escolha usando uma escolha global.

Propriedades do atributo Picklist	Values
`SchemaName`	`sample_Colors`
`DisplayName`	Cores de exemplo
`Description`	Atributo de Lista de Seleção Global de Cores
`RequiredLevel`	`None`
`GlobalOptionSet`	Defina essa propriedade de navegação com valor único usando a `@odata.bind` sintaxe com uma referência à escolha global. Este exemplo usa a `MetadataId` chave como chave, mas também pode usar a chave alternativa com `Name`: `GlobalOptionSetDefinitions(Name='sample_colors')`

O exemplo a seguir cria uma coluna local usando as propriedades e a adiciona à sample_bankaccount tabela.

A resposta retorna o URI do atributo.

Solicitação:

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

Resposta:

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)

Opções de inserção

O exemplo a seguir usa a Ação InsertOptionValue para adicionar uma nova opção com o valor 727000005e rotular Echo à coluna de escolha local criada por Criar uma coluna de escolha.

Solicitação:

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

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

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

Opções de atualização

Para atualizar as opções individuais, use a Ação UpdateOptionValue. O exemplo a seguir atualiza o TrueOption exemplo da coluna booliana em Criar uma coluna booliana e altera o rótulo em Up vez de True. Como esse conjunto de opções é local, o exemplo usa AttributeLogicalName e EntityLogicalName. Para um conjunto de opções global, use o OptionSetName parâmetro em vez disso.

Solicitação:

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
}

Resposta:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Opções de pedido

O exemplo a seguir mostra como reordenar opções em um conjunto de opções local usando a Ação OrderOption. A Value propriedade contém os valores da opção na ordem desejada.

Para usar essa ação com um conjunto de opções global, especifique o OptionSetName parâmetro em vez de EntityLogicalName e AttributeLogicalName.

Use o SolutionUniqueName parâmetro para aplicar as alterações como parte da solução especificada.

Solicitação:

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

Resposta:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Opção Excluir

O exemplo a seguir mostra como excluir uma opção em uma coluna de escolha local usando a Ação DeleteOptionValue.

Para usar essa ação com um conjunto de opções global, especifique o OptionSetName parâmetro em vez de EntityLogicalName e AttributeLogicalName.

Use o SolutionUniqueName parâmetro para aplicar as alterações como parte da solução especificada.

Solicitação:

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
}

Resposta:

HTTP/1.1 204 NoContent
OData-Version: 4.0

Inserir valor de status

O exemplo a seguir mostra como adicionar uma opção a uma coluna de status usando a Ação InsertStatusValue.

Use o StateCode parâmetro para especificar a opção statecode à qual o valor de status se aplica. O SolutionUniqueName parâmetro aplica as alterações como parte da solução especificada.

A NewOptionValue propriedade retornada pelo ComplexType InsertStatusValueResponse contém o valor atribuído à opção.

Solicitação:

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

Resposta:

HTTP/1.1 200 OK
OData-Version: 4.0

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

Consulte também

Personalizar opções
Criar e editar a visão geral das opções globais
Criar uma opção

Comentários

Esta página foi útil?

Last updated on 2026-08-14

Criar e atualizar opções (conjuntos de opções) usando a API Web

Operações de API Web para opções

Exemplos de API Web para opções

Criar um conjunto de opções globais

Criar uma coluna de escolha usando um conjunto de opções global

Opções de inserção

Opções de atualização

Opções de pedido

Opção Excluir

Inserir valor de status

Consulte também

Comentários

Recursos adicionais