Tabelas Catálogo e Atribuição de Catálogo

Utilize as tabelas Catalog e CatalogAssignment para criar uma estrutura para expor as ações usadas em sua solução como eventos de negócios. Os Eventos de negócios do Microsoft Dataverse permitem muitos cenários para criar integrações com outros aplicativos por meio do Dataverse. Mais informações: Eventos de negócios do Microsoft Dataverse

Seu catálogo descreverá os eventos relevantes para sua solução para que as pessoas possam usá-los. Se você não catalogar os eventos relevantes para sua solução, eles poderão não estar disponíveis para as pessoas que usam sua solução.

Use a tabela Catalog para criar uma hierarquia de dois níveis. Isso criará um grupo catálogo e categoria em que o catálogo de segundo nível representa a categoria.

O catálogo de primeiro nível deve representar sua solução. Use vários catálogos de segundo nível relacionados ao seu catálogo de primeiro nível para agrupar diferentes categorias de funcionalidade em sua solução.

Para cada catálogo de segundo nível que representa as categorias em sua solução, você usará a tabela CatalogAssignment para especificar tabelas, API personalizadas ou ações de Processo Personalizado que você deseja que estejam disponíveis como eventos.

Importante

Os usuários com a função de segurança do Environment Maker podem exibir os dados do Catálogo no conector do Dataverse Power Automate Quando uma ação é executada. Outras funções de segurança devem ter um privilégio de leitura de nível de acesso apropriado para estas tabelas: API Personalizada, Processo, Mensagem do SDK.

Mais informações:

Exemplo: Gerenciamento de Clientes da Contoso

Para introduzir a ideia de um catálogo, vamos começar com um exemplo.

A solução de gerenciamento de clientes contoso contém muitos componentes. Os únicos componentes de interesse aqui são:

  • Tables
  • API personalizada
  • Ação de processo personalizado (fluxo de trabalho)

Tables

O gerenciamento de clientes da Contoso é uma solução que inclui as seguintes tabelas:

SchemaName Nome de exibição Description
Account Conta Uma tabela do sistema Dataverse
Contact Contato Uma tabela do sistema Dataverse
contoso_Membership Membership Uma tabela personalizada de propriedade da organização

API personalizada

Eles também criaram várias ações de API personalizadas que são chamadas por seu sistema de ponto de venda, seu site e sistemas ERP para notificar o Dataverse de eventos que não se originam no Dataverse:

UniqueName DisplayName
contoso_CustomerEnteredStore Loja Inserida
contoso_CustomerVisitWebSite Visite o Site da Web
contoso_CustomerPurchasedProduct Produto comprado
contoso_CustomerReturnedProduct Produto retornado

Estrutura de catálogo

O catálogo de soluções de gerenciamento de clientes da Contoso tem esta aparência:

Catalog Description
Gerenciamento de Clientes da Contoso Catálogo raiz
    Tables Categoria de catálogo de 2º nível
            Conta CatalogAssignment: Entidade
            Contato CatalogAssignment: Entidade
            Membership CatalogAssignment: Entidade
    Eventos de cliente Categoria de catálogo de 2º nível
            Loja Inserida CatalogAssignment: CustomAPI
            Visite o Site da Web CatalogAssignment: CustomAPI
            Comprar produto CatalogAssignment: CustomAPI
            Retornar produto CatalogAssignment: CustomAPI

Eventos disponíveis

Quando você faz uma CatalogAssignment em uma tabela, algumas operações associadas ao sistema para essa tabela ficam disponíveis como eventos.

Com este catálogo, os seguintes eventos estarão disponíveis:

Table Event Por que está disponível?
Conta Create
Update
Delete		 Operação padrão de dados
Conta ConcederAcesso
ModificarAcesso
RevogarAcesso		 A entidade de propriedade do usuário pode ser compartilhada.
Contato Create
Update
Delete		 Operação padrão de dados
Contato ConcederAcesso
ModificarAcesso
RevogarAcesso		 A entidade de propriedade do usuário pode ser compartilhada.
Membership Create
Update
Delete		 Operação padrão de dados
N/A contoso_CustomerEnteredStore Atribuição explícita de catálogo
N/A contoso_CustomerVisitWebSite Atribuição explícita de catálogo
N/A contoso_CustomerPurchasedProduct Atribuição explícita de catálogo
N/A contoso_CustomerReturnedProduct Atribuição explícita de catálogo

A maioria das tabelas dará suporte aos eventos Criar, Atualizar e Excluir. Há algumas exceções. As tabelas de propriedade do usuário exporão eventos para alterações no compartilhamento: GrantAccess, ModifyAccess e RevokeAccess

Note

Qualquer API personalizada ou ações de processo personalizadas associadas à tabela também serão incluídas.

Ações de processo personalizadas desabilitadas serão mostradas, mas o evento nunca ocorrerá até que sejam habilitadas e usadas.

Criar um catálogo no Power Apps

Você pode criar registros de Catálogo e Atribuição de Catálogo no Power Apps (https://make.powerapps.com).

Você sempre deve criar um catálogo como parte de uma solução. Use as instruções a seguir para criar registros de catálogo:

  1. Entre no Power Apps,

  2. No painel de navegação esquerdo, selecione Soluções.

  3. Crie ou selecione uma solução que você deseja usar e clique em Novo.

  4. Selecione Catálogo no menu e uma nova janela será aberta.

  5. Introduza os seguintes campos:

    Field Description
    Catálogo principal Não defina um catálogo pai para o catálogo raiz da solução. Caso contrário, defina o catálogo raiz da solução.
    Nome único O nome único deve ter um prefixo de personalização e não ter espaços. Esse prefixo deve ser o mesmo que o prefixo de personalização para o editor de soluções.
    Name Insira um nome para o catálogo. Geralmente o mesmo que o Nome Único, mas sem o prefixo de personalização e com espaços.
    Nome de exibição Normalmente, o mesmo que o Nome.
    Description Insira uma descrição significativa do catálogo.

  6. Salve e feche o formulário.

Criar uma atribuição de catálogo no Power Apps

Usando a mesma solução que contém o catálogo no Power Apps

  1. Clique em Novo.

  2. Selecione Atribuição de Catálogo no menu e uma nova janela será aberta.

  3. Insira o Nome. Esse valor deve começar com um prefixo de personalização e não ter espaços. Você deve usar o mesmo prefixo de personalização definido para o publicador da solução.

  4. Defina o objeto de atribuição de catálogo. Essa pesquisa permite definir três tipos diferentes de registros:

    • APIs Personalizadas
    • Entities
    • Processos

    Você deve ser capaz de descobrir o tipo que está procurando digitando o nome.

  5. Selecionar um catálogo

    Note

    O catálogo selecionado deve ser um catálogo de segundo nível que representa uma categoria.

  6. Salvar e fechar o formulário

Bloquear a personalização de itens de catálogo em sua solução gerenciada

A menos que você queira permitir que as pessoas que instalam sua solução gerenciada possam personalizar o catálogo e as atribuições de catálogo, você deve ter certeza de definir a propriedade IsCustomizable como false, porque o valor padrão permite que elas sejam personalizadas.

Para definir isso na interface do usuário do Power Apps:

  1. Selecione cada atribuição de catálogo ou catálogo em sua solução

  2. No menu, clique nas reticências (...) e selecione Propriedades Gerenciadas.

    Clique nas reticências para exibir o botão Propriedades Gerenciadas.

  3. Na janela que é aberta, desmarque Allow customizations.

    Desmarque Permitir personalizações.

  4. Clique em Concluído

Diagrama de tabela

O diagrama a seguir mostra as relações entre as tabelas Catalog e CatalogAssignment

Diagrama de tabelas Catalog e CatalogAssignment

A relação auto-referencial que usa ParentCatalogId é o que permite a criação da hierarquia de dois níveis entre um catálogo de soluções e vários catálogos que representam categorias usando registros de catálogo.

Colunas de tabela de catálogo

Todas as colunas e relações disponíveis estão disponíveis na referência de tabela/entidade do catálogo.

A tabela a seguir inclui colunas/atributos selecionados de uma tabela/entidade de catálogo que você pode definir.

Nome de exibição
SchemaName
LogicalName		 Tipo Description
Catalog
CatalogId
catalogid		 Identificador exclusivo Identificador exclusivo para instâncias de catálogo.
Description
Description
description		 String Descrição localizada para instâncias de catálogo.
Required
Nome de exibição
DisplayName
displayname		 String Nome de exibição localizado para instâncias de catálogo.
Required
É Personalizável
IsCustomizable
iscustomizable		 ManagedProperty Controla se o Catálogo pode ser personalizado ou excluído.
O valor padrão é verdadeiro. Mais informações: bloquear a personalização de itens de catálogo em sua solução gerenciada
Required
Name
Name
name		 String O nome principal do catálogo.
Required
Catálogo principal
ParentCatalogId
parentcatalogid		 Lookup Identificador exclusivo para o Catálogo Pai.
Não é possível alterar depois que ele é salvo.
Nome único
UniqueName
uniquename		 String Nome exclusivo para o catálogo.
Required
Deve começar com um prefixo de personalização.

Note

Ao associar uma Atribuição de Catálogo a um Catálogo, você não poderá excluir o catálogo até remover a atribuição de catálogo.

Colunas da tabela CatalogAssignment

Todas as colunas e relações disponíveis estão disponíveis na referência de tabela/entidade CatalogAssignment.

A tabela a seguir inclui colunas/atributos selecionados de uma tabela/entidade CatalogAssignment que você pode definir.

Nome de exibição
SchemaName
LogicalName		 Tipo Description
Atribuição de Catálogo
CatalogAssignmentId
catalogassignmentid		 Identificador exclusivo Identificador exclusivo para instâncias de atribuição de catálogo.
catálogo
CatalogId
catalogid		 Lookup Identificador exclusivo para o catálogo associado à atribuição de catálogo.
Required
É Personalizável
IsCustomizable
iscustomizable		 ManagedProperty Controla se o CatalogAssignment pode ser personalizado ou excluído.
O valor padrão é verdadeiro. Mais informações: bloquear a personalização de itens de catálogo em sua solução gerenciada
Required
Name
Name
name		 String O nome principal da atribuição do catálogo.
Objeto de atribuição de catálogo
Object
object		 Lookup Identificador exclusivo para o objeto associado à atribuição de catálogo.
Required
Não é possível alterar depois que ele é salvo.
Essa consulta polimórfica pode ser vinculada às seguintes tabelas:
  customapi
  entidade
  fluxo de trabalho

Ao usar a API Web para associar essa relação polimórfica, você deve usar os nomes de propriedade de navegação de valor único para cada relação.

Estes nomes são:
  CustomAPIId
  EntityId
  WorkflowId

Ao associar a uma tabela, a uma API personalizada ou a uma ação de processo personalizada, você precisará obter o valor do respectivo ID. Consulte Obter a ID dos itens CatalogAssignment para obter mais informações.

Obter o ID dos itens de CatalogAssignment

Você precisará obter a ID de entidades, apis personalizadas e ações de processo personalizadas ao associá-las a um CatalogAssignment.

Obter o ID de uma tabela

A tabela Entity contém uma linha para cada entidade. Você pode obter a ID de uma tabela específica, como a tabela Conta, usando qualquer uma dessas consultas usando a API Web:

GET [Organization URI]/api/data/v9.2/EntityDefinitions(LogicalName='account')?$select=MetadataId

GET [Organization URI]/api/data/v9.2/entities?$select=entityid&$filter=name eq 'Account'

Obter a ID de uma API personalizada

Isso é feito com mais facilidade usando a API Web. O exemplo a seguir retornará a customapiid de uma api personalizada com a uniquename de your_CustomAPIName.

GET [Organization URI]/api/data/v9.2/customapis?$select=customapiid&$filter=uniquename eq 'your_CustomAPIName'

Obter a ID de uma ação de processo personalizado

Isso é feito com mais facilidade usando a API Web. O exemplo a seguir retornará o resultado workflowid de uma ação de processo personalizada com o uniquename de ExampleCustomProcessAction.

GET [Organization URI]/api/data/v9.2/workflows?$select=workflowid,uniquename&$filter=category eq 3 and type eq 1 and endswith(uniquename,'ExampleCustomProcessAction')

Note

O uniquename do fluxo de trabalho não inclui o prefixo de personalização que é prefixado ao nome da ação de processo personalizado na API Web. Se a ação que você chama da API Web for nomeada new_ExampleCustomProcessAction, o nome exclusivo do fluxo de trabalho será ExampleCustomProcessAction.

Certifique-se de acessar a linha em que o Tipo é 1. Essa é a definição de fluxo de trabalho.

Os fluxos de trabalho de ação de processo personalizado têm o valor de 3 em Category.

Recuperar atribuições de catálogo existentes

Você pode usar a consulta OData a seguir para recuperar informações sobre Atribuições de Catálogo, o tipo de atribuição, o catálogo ao qual eles estão associados e o catálogo pai.

GET [Organization URI]/api/data/v9.2/catalogassignments?$select=name
    &$expand=CatalogId($select=uniquename;$expand=ParentCatalogId($select=uniquename)),
    EntityId($select=entityid),
    CustomAPIId($select=uniquename),
    WorkflowId($select=uniquename)
    &$filter=name ne null

Criar Catálogos e CatalogAssignments com código

Você pode criar catálogos e registros de atribuição de catálogo usando a API Web ou o SDK para .NET.

Usando a API Web

Note

No momento, não é possível criar registros de catálogo e de atribuição de catálogo usando 'deep-insert'.

Você pode criar uma hierarquia de registros de catálogo usando 'deep-insert', mas você deve criar as atribuições de catálogo individualmente.

A seguinte série de operações de API Web criará uma hierarquia de catálogo e um CatalogAssignment em uma solução com o UniqueName: ContosoCustomerManagement. Observe o uso do cabeçalho da solicitação MSCRM.SolutionUniqueName para definir a associação à solução quando o registro é criado.

Consulte a seção Criar um registro usando a API Web: Criação básica e Associar linhas de tabela na criação para obter mais informações.

Criar o catálogo raiz

Solicitação:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management",
    "uniquename": "contoso_CustomerManagement",
    "displayname": "Contoso Customer Management",
    "description": "The root catalog for the Contoso Customer Management solution",
    "iscustomizable": {
        "Value": false
    }
}

Resposta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)

Criar o subcatálogo de eventos de tabela

Solicitação:

POST [Organization URI]/api/data/v9.2/catalogs HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Contoso Customer Management Table Events",
    "uniquename": "contoso_TableEvents",
    "displayname": "Tables",
    "description": "Groups Table events for the Contoso Customer Management Solution",
    "iscustomizable": {
        "Value": false
    },
    "ParentCatalogId@odata.bind": "catalogs(a0a0a0a0-bbbb-cccc-dddd-e1e1e1e1e1e1)"
}

Resposta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)

Criar a Account Catalog Assignment no catálogo de tabelas

Consulte Obter a ID de uma tabela para obter informações sobre a ID de uma tabela.

Solicitação:

POST [Organization URI]/api/data/v9.2/catalogassignments HTTP/1.1
MSCRM.SolutionUniqueName: ContosoCustomerManagement
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
{
    "name": "Account",
    "EntityId@odata.bind": "entities(70816501-edb9-4740-a16c-6a5efbc05d84)",
    "iscustomizable": {
        "Value": false
    },
    "CatalogId@odata.bind": "catalogs(b1b1b1b1-cccc-dddd-eeee-f2f2f2f2f2f2)"
}

Resposta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(c2c2c2c2-dddd-eeee-ffff-a3a3a3a3a3a3)

Usando o SDK para .NET

O código a seguir mostra a criação de uma hierarquia de catálogo e uma atribuição de catálogo em uma solução com o UniqueName: ContosoCustomerManagement.

Note

Use o SolutionUniqueName parâmetro opcional com a Classe CreateRequest para criar os registros no contexto dessa solução. Mais informações: Passando parâmetros opcionais com uma solicitação

string conn = $@"
Url = {url};
AuthType = OAuth;
UserName = {userName};
Password = {password};
AppId = 51f81489-12ee-4a9e-aaae-a2591f45987d;
RedirectUri = app://58145B91-0C36-4500-8554-080854F2AC97;
LoginPrompt=Auto;
RequireNewInstance = True";

var service = new CrmServiceClient(conn);
// var service = new ServiceClient(conn);

var solutionUniqueName = " ContosoCustomerManagement ";

//Create the root catalog
Catalog rootCatalog = new Catalog
{
    Name = "Contoso Customer Management",
    UniqueName = "contoso_CustomerManagement",
    DisplayName = "Contoso Customer Management",
    Description = "The root catalog for the Contoso Customer Management solution",
    IsCustomizable = new BooleanManagedProperty(false)
};

CreateRequest rootCatalogReq = new CreateRequest {
    Target = rootCatalog
};
rootCatalogReq["SolutionUniqueName"] = solutionUniqueName;

Guid rootCatalogId = ((CreateResponse)service.Execute(rootCatalogReq)).id;

//Create the Table Events Sub-catalog
Catalog tableEvents = new Catalog
{
    Name = "Contoso Customer Management Table Events",
    UniqueName = "contoso_TableEvents",
    DisplayName = "Tables",
    Description = "Groups Table events for the Contoso Customer Management Solution",
    IsCustomizable = new BooleanManagedProperty(false),
    ParentCatalogId = new EntityReference("catalog", rootCatalogId)
};

CreateRequest tableEventsReq = new CreateRequest
{
    Target = tableEvents
};
tableEventsReq["SolutionUniqueName"] = solutionUniqueName;

Guid tableEventsId = ((CreateResponse)service.Execute(tableEventsReq)).id;

//Create the Account Catalog Assignment on the Tables catalog
CatalogAssignment accountAssignment = new CatalogAssignment
{
    Name = "Account",
    IsCustomizable = new BooleanManagedProperty(false),
    Object = new EntityReference("entity",new Guid("70816501-edb9-4740-a16c-6a5efbc05d84")),
    CatalogId = new EntityReference("catalog", tableEventsId)

};

CreateRequest accountAssignmentReq = new CreateRequest
{
    Target = accountAssignment
};
accountAssignmentReq["SolutionUniqueName"] = solutionUniqueName;

Guid accountAssignmentId = ((CreateResponse)service.Execute(accountAssignmentReq)).id;

Criar catálogo e atribuições de catálogo editando arquivos de solução

Em um arquivo de solução, você pode editar os arquivos para criar catálogos e atribuições de catálogos.

Use a ferramenta SolutionPackager para extrair uma solução em arquivos que podem ser gerenciados no controle do código-fonte. Em seguida, você pode editar os arquivos. Em seguida, você pode usar SolutionPackager para empacotar os arquivos extraídos de volta em uma solução. Mais informações: Controle do código-fonte com arquivos de solução

Dica

Crie alguns catálogos e atribuições de catálogo em uma solução e, em seguida, exporte e extraia a solução para ver alguns exemplos.

Verifique se você está usando a versão mais recente do Microsoft.CrmSdk.CoreTools NuGet Package

Criar um catálogo com arquivos de solução

Em uma solução, todos os catálogos estarão dentro de uma catalogs pasta. Você pode criar, modificar ou remover catálogos editando as pastas e arquivos nessa pasta e importando a solução depois que ela tiver sido empacotada usando o empacotador de soluções.

Cada catálogo será incluído em uma pasta correspondente ao uniquename do catálogo, como contoso_CustomerManagement.

Dentro da pasta há um catalog.xml arquivo que contém a definição do catálogo.

Por exemplo:

<catalog uniquename="contoso_CustomerManagement">
    <description default="The root catalog for the Contoso Customer Management solution">
        <label description="The root catalog for the Contoso Customer Management solution" languagecode="1033" />
    </description>
    <displayname default="Contoso Customer Management">
        <label description="Contoso Customer Management" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management</name>
</catalog>

O atributo do elemento uniquename deve corresponder ao nome da pasta que contém o arquivo.

O catalog elemento inclui estes elementos:

Element Description
description Tem um default atributo com o valor da descrição padrão.
Contém um ou mais label elementos com atributos para description e languagecode quando vários idiomas são definidos.
displayname Tem um default atributo com o valor do nome de exibição padrão.
Contém um ou mais label elementos com atributos para description e languagecode quando vários idiomas são definidos.
iscustomizable Se o catálogo é personalizável. 0 = false, 1 = true.
name O nome do catálogo.

Se o catálogo representar uma categoria, a relação com o catálogo pai será incluída usando um parentcatalogid elemento que contém um uniquename elemento que contém o nome exclusivo do catálogo pai.

Por exemplo:

<catalog uniquename="contoso_TableEvents">
    <description default="Groups Table events for the Contoso Customer Management Solution">
        <label description="Groups Table events for the Contoso Customer Management Solution" languagecode="1033" />
    </description>
    <displayname default="Tables">
        <label description="Tables" languagecode="1033" />
    </displayname>
    <iscustomizable>0</iscustomizable>
    <name>Contoso Customer Management Table Events</name>
    <parentcatalogid>
        <uniquename>contoso_CustomerManagement</uniquename>
    </parentcatalogid>
</catalog>

Criar um CatalogAssignment com arquivos de solução

Em uma solução, na pasta Assets, você encontrará um arquivo catalogassignments.xml. Todas as atribuições de catálogo são incluídas no arquivo. Você pode criar ou modificar atribuições de catálogo editando esse arquivo e importando a solução depois que ela tiver sido empacotada usando o empacotador de solução.

Por exemplo:

<catalogassignments>
    <catalogassignment object.logicalname="account" catalogid.uniquename="contoso_TableEvents" objectidtype="entity">
        <iscustomizable>0</iscustomizable>
        <name>Account</name>
    </catalogassignment>
    <catalogassignment catalogid.uniquename="contoso_CustomerEvents" object.uniquename="contoso_CustomerEnteredStore" objectidtype="customapi">
        <iscustomizable>0</iscustomizable>
        <name>Customer Entered Store</name>
  </catalogassignment>
</catalogassignments>

Cada catalogassignment elemento tem estes atributos:

Attribute Description
catalogid.uniquename Nome exclusivo do subcatálogo ao qual a atribuição de catálogo se refere.
objecttypeid O tipo de objeto. Os valores válidos são:
entity
customapi
workflow

Dependendo do objectypeidelemento , cada catalogassignment elemento deve ter um destes atributos correspondentes:

Attribute Description
object.uniquename O nome exclusivo da api personalizada.
object.logicalname O nome lógico da entidade.
object.workflowid O valor de ID exclusivo da ação de processo personalizado.

O catalogassignment elemento inclui estes elementos:

Element Description
iscustomizable Se a atribuição de catálogo é personalizável. 0 = false, 1 = true.
name O nome da atribuição de catálogo

Consulte também

Eventos empresariais do Microsoft Dataverse
Criar um registro de entidade usando a API Web
Recuperar um registro de entidade usando a API Web
Criar entidades usando o SDK para .NET
Recuperar uma entidade usando o SDK para .NET

  • Última atualização a