Partekatu honen bidez:

Catálogo y tablas de asignación de catálogo

  • Artikulua

Utilice las tablas Catalog y CatalogAssignment para crear una estructura para exponer las acciones utilizadas en su solución como eventos comerciales. Los eventos empresariales de Microsoft Dataverse permiten que muchos escenarios creen integraciones con otras aplicaciones a través de Dataverse. Más información: Eventos empresariales de Microsoft Dataverse

Su catálogo describirá aquellos eventos que son relevantes para su solución para que las personas puedan usarlos. Si no cataloga los eventos relevantes para su solución, es posible que no estén disponibles para las personas que utilizan su solución.

Use la tabla Catalog para crear una jerarquía de dos niveles. Esto creará un grupo Catálogo y Categoría donde el catálogo de segundo nivel representa la categoría.

El catálogo de primer nivel debe representar su solución. Utilice varios catálogos de segundo nivel relacionados con su catálogo de primer nivel para agrupar diferentes categorías de funcionalidades dentro de su solución.

Para cada catálogo de segundo nivel que represente las categorías dentro de su solución, utilizará la tabla CatalogAssignment para especificar las acciones de Tablas, API personalizadas o Procesos personalizados que desee que estén disponibles como eventos.

Importante

Los usuarios con el rol de seguridad Creador entorno pueden ver los datos del catálogo en el conector Dataverse de Power Automate, en el desencadenador Cuando se realiza una acción. Otros roles de seguridad deben tener el privilegio de lectura de nivel adecuado para estas tablas: API personalizada, Proceso, Mensaje de SDK.

Más información:

Ejemplo: administración de clientes de Contoso

Para presentar la idea de un catálogo, comencemos con un ejemplo.

La solución de administración de clientes de Contoso contiene muchos componentes. Los únicos componentes que interesan aquí son:

  • Tablas
  • API personalizada
  • Acción de proceso personalizada (flujo de trabajo)

Tablas

La administración de clientes de Contoso es una solución que incluye las siguientes tablas:

SchemaName Nombre Descripción
Account Cuenta Una tabla del sistema de Dataverse
Contact CONTACTO Una tabla del sistema de Dataverse
contoso_Membership Pertenencia Una tabla personalizada propiedad de la organización

API personalizada

También han creado una serie de acciones de API personalizadas a las que llama su sistema de punto de venta, su sitio web y los sistemas ERP para notificar a Dataverse de eventos que no se originan en Dataverse:

UniqueName Nombre para mostrar
contoso_CustomerEnteredStore Tienda donde se ha entrado
contoso_CustomerVisitWebSite Visitar sitio web
contoso_CustomerPurchasedProduct Producto comprado
contoso_CustomerReturnedProduct Producto devuelto

Estructura del catálogo

El catálogo de soluciones de administración de clientes de Contoso tiene este aspecto:

Catálogo Descripción
Administraión de clientes de Contoso Catálogo raíz
    Tablas Categoría de catálogo de segundo nivel
            Cuenta CatalogAssignment: entidad
            CONTACTO CatalogAssignment: entidad
            Pertenencia CatalogAssignment: entidad
    Eventos de cliente Categoría de catálogo de segundo nivel
            Tienda donde se ha entrado CatalogAssignment: CustomAPI
            Visitar sitio web CatalogAssignment: CustomAPI
            Comprar producto CatalogAssignment: CustomAPI
            Devolver producto CatalogAssignment: CustomAPI

Eventos disponibles

Cuando hace un CatalogAssignment a una tabla, algunas operaciones vinculadas al sistema para esa tabla están disponibles como eventos.

Con este catálogo estarán disponibles los siguientes eventos:

Tabla Evento Por qué está disponible
Cuenta Crear
Actualización
Delete		 Operación de datos estándar
Cuenta GrantAccess
ModifyAccess
RevokeAccess		 La entidad propiedad del usuario se puede compartir.
CONTACTO Crear
Actualización
Delete		 Operación de datos estándar
CONTACTO GrantAccess
ModifyAccess
RevokeAccess		 La entidad propiedad del usuario se puede compartir.
Pertenencia Crear
Actualización
Delete		 Operación de datos estándar
N/D contoso_CustomerEnteredStore Asignación de catálogo explícita
N/D contoso_CustomerVisitWebSite Asignación de catálogo explícita
N/D contoso_CustomerPurchasedProduct Asignación de catálogo explícita
N/D contoso_CustomerReturnedProduct Asignación de catálogo explícita

La mayoría de las tablas admitirán eventos Crear, Actualizar y Borrar. Hay algunas excepciones. Las tablas propiedad del usuario expondrán eventos para cambios en el uso compartido: GrantAccess, ModifyAccess, y RevokeAccess

Nota

También se incluirá cualquier API personalizada o acciones de proceso personalizadas que estén vinculadas a la tabla.

Se mostrarán las acciones de proceso personalizadas que están deshabilitadas, pero el evento nunca ocurrirá hasta que estén habilitadas y utilizadas.

Crear un catálogo en Power Apps

Puede crear registros Catálogo y Asignación de catálogo en Power Apps (https://make.powerapps.com).

Siempre debe crear un catálogo como parte de una solución. Utilice las siguientes instrucciones para crear registros de catálogo:

  1. Inicie sesión en Power Apps.

  2. En el panel de navegación izquierdo, seleccione Soluciones.

  3. Cree o seleccione una solución que desee utilizar, luego haga clic en Nueva.

  4. Seleccione Catálogo en el menú y se abrirá una nueva ventana.

  5. Introduzca los campos siguientes:

    Campo Descripción
    Catálogo principal No establezca un catálogo principal para el catálogo raíz de la solución. De lo contrario, configure el catálogo raíz de la solución.
    Nombre único El nombre exclusivo debe tener un prefijo de personalización y no debe tener espacios. Este prefijo debería ser el mismo que el prefijo de personalización para el editor de soluciones.
    Asignar nombre Escriba un nombre para el catálogo. Normalmente el mismo que el Nombre único, pero sin el prefijo de personalización y con espacios.
    Nombre Normalmente lo mismo que el Nombre.
    Descripción Escriba una descripción relevante del catálogo.

  6. Guardar y cerrar el formulario.

Cree una Asignación de catálogo en Power Apps

Usando la misma solución que contiene el catálogo en Power Apps

  1. Haga clic en Nueva.

  2. Seleccione Asignación de catálogo en el menú y se abrirá una nueva ventana.

  3. Escriba el Nombre. Este valor debe empezar con un prefijo de personalización y no debe tener espacios. Debería usar el mismo prefijo de personalización definido por su editor de soluciones.

  4. Establezca el Objeto de asignación de catálogo. Esta búsqueda permite configurar tres tipos diferentes de registros:

    • API personalizadas
    • Entidades
    • Procesos

    Debería poder descubrir el tipo que está buscando escribiendo el nombre.

  5. Seleccionar un catálogo

    Nota

    El catálogo que seleccione debe ser un catálogo de segundo nivel que represente una categoría.

  6. Guardar y cerrar el formulario

Bloquea la personalización de los elementos del catálogo en su solución administrada

A menos que desee permitir que las personas que instalan su solución administrada puedan personalizar el catálogo y las asignaciones del catálogo, debe asegurarse de establecer la propiedad IsCustomizable a false porque el valor predeterminado permite personalizarlos.

Para establecer esto en la interfaz de usuario de Power Apps:

  1. Seleccione cada catálogo o asignación de catálogo dentro de su solución

  2. En el menú, haga clic en las elipses (...) y seleccione Propiedades administradas.

    Haga clic en los puntos suspensivos para ver el botón de propiedades administradas.

  3. En la ventana que se abre, anule la selección Permitir personalizaciones.

    Anule la selección de Permitir personalizaciones.

  4. Haga clic en Listo

Diagrama de tabla

En el siguiente diagrama se muestran las relaciones entre las tablas Catalog y CatalogAssignment

Diagrama de tablas Catalog y CatalogAssignment

La relación autorreferencial usando ParentCatalogId es lo que permite crear la jerarquía de dos niveles entre un catálogo de soluciones y varios catálogos que representan categorías utilizando registros de catálogo.

Columnas de tabla de catálogo

Todas las columnas y relaciones están disponibles en Referencia de tabla o entidad de catálogo.

La siguiente tabla incluye columnas/atributos seleccionados de una tabla o entidad de catálogo que puede configurar.

Nombre
SchemaName
LogicalName		 Tipo Descripción
Catálogo
CatalogId
catalogid		 Uniqueidentifier Identificador único de instancias del catálogo.
Descripción
Description
description		 String Descripción localizada de las instancias del catálogo.
Necesario
Nombre
DisplayName
displayname		 String Nombre para mostrar localizado de las instancias del catálogo.
Necesario
Es personalizable
IsCustomizable
iscustomizable		 ManagedProperty Controla si el catálogo se puede personalizar o eliminar.
El valor predeterminado es verdadero. Más información: Bloquear la personalización de los elementos del catálogo en su solución administrada
Necesario
Asignar nombre
Name
name		 String Nombre principal del catálogo.
Necesario
Catálogo principal
ParentCatalogId
parentcatalogid		 Búsqueda Identificador único del catálogo principal.
No se pueden cambiar después de guardarlos.
Nombre único
UniqueName
uniquename		 String Nombre único para el catálogo.
Necesario
Debe comenzar con un prefijo de personalización.

Nota

Cuando asocie una asignación de catálogo a un catálogo, no podrá eliminar el catálogo hasta que elimine la asignación de catálogo.

Columnas de tabla de CatalogAssignment

Todas las columnas y relaciones están disponibles en Referencia de tabla o entidad de CatalogAssignment.

La siguiente tabla incluye columnas/atributos seleccionados de una tabla o entidad de CatalogAssignment que puede configurar.

Nombre
SchemaName
LogicalName		 Tipo Descripción
Asignación de catálogo
CatalogAssignmentId
catalogassignmentid		 Uniqueidentifier Identificador único de las instancias de asignación de catálogo.
catálogo
CatalogId
catalogid		 Búsqueda Identificador único del catálogo asociado con la asignación de catálogo.
Necesario
Es personalizable
IsCustomizable
iscustomizable		 ManagedProperty Controla si el CatalogAssignment se puede personalizar o eliminar.
El valor predeterminado es verdadero. Más información: Bloquear la personalización de los elementos del catálogo en su solución administrada
Necesario
Asignar nombre
Name
name		 String Nombre principal de la asignación de catálogo.
Objeto de asignación de catálogo
Object
object		 Búsqueda Identificador único del objeto asociado con la asignación de catálogo.
Necesario
No se pueden cambiar después de guardarlos.
Esta búsqueda polimórfica se puede vincular a las siguientes tablas:
  customapi
  entidad
  flujo de trabajo

Al utilizar la API web para asociar esta relación polimórfica, debe utilizar los nombres de propiedad de navegación de un solo valor para cada relación.

Estos nombres son:
  CustomAPIId
  EntityId
  WorkflowId

Cuando se asocia a una tabla, una api personalizada o una acción de proceso personalizada, deberá obtener el valor respectiveid. Consulte Obtener el id. de los elementos de CatalogAssignment para más información.

Obtener el id. de los elementos de CatalogAssignment

Deberá obtener el id. de las entidades, las apis personalizadas y las acciones de proceso personalizadas cuando las asocie con una CatalogAssignment.

Obtener el id. de una tabla

La tabla Entidad contiene una fila para cada tabla. Puede obtener el id. de una tabla específica, como la tabla Cuenta, mediante cualquiera de estas consultas mediante la 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'

Obtener el id. de una API personalizada

Esto se hace más fácilmente usando la API web. El siguiente ejemplo devolverá el customapiid de una api personalizada con el uniquename de your_CustomAPIName.

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

Obtener el id. de una acción de proceso personalizada

Esto se hace más fácilmente usando la API web. El siguiente ejemplo devolverá el workflowid de una acción de proceso personalizada con el 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')

Nota

El uniquename del flujo de trabajo no incluye el prefijo de personalización que se antepone al nombre de la acción del proceso personalizado en la API web. Si la acción que llama desde la API web se llama new_ExampleCustomProcessAction, el nombre único del flujo de trabajo será ExampleCustomProcessAction.

Asegúrese de acceder a la fila donde Tipo sea 1. Este es la definición de flujo de trabajo.

Los flujos de trabajo de acciones de procesos personalizados tienen un valor de Categoría de 3.

Recuperar asignaciones de catálogo existentes

Puede utilizar la siguiente consulta de OData para recuperar información sobre las asignaciones de catálogo, el tipo de asignación, el catálogo con el que están asociadas y el catálogo principal.

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

Consulte Crear Catálogos y CatalogAssignments con código

Puede crear catálogos y registros de asignación de catálogos utilizando la API web o el SDK para .NET.

Uso de la API web

Nota

En este momento no es posible crear catálogos y registros de asignación de catálogos usando 'deep-insert'.

Puede crear una jerarquía de registros de catálogo utilizando 'inserción profunda', pero debe crear las asignaciones de catálogo individualmente.

La siguiente serie de operaciones de API web creará una jerarquía de catálogo y una CatalogAssignment en una solución con UniqueName: ContosoCustomerManagement. Tenga en cuenta el uso del encabezado de solicitud MSCRM.SolutionUniqueName para establecer la asociación a la solución cuando se crea el registro.

Consulte las secciones Crear un registro usando la API web: Creación básica y Filas de tabla asociada al crear para más información.

Crear el catálogo raíz

Solicitud:

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

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogs(00000000-0000-0000-0000-000000000001)

Crear el subcatálogo de eventos de tabla

Solicitud:

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(00000000-0000-0000-0000-000000000001)"
}

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(00000000-0000-0000-0000-000000000002)

Crear la asignación del catálogo de cuentas en el catálogo de tablas

Consulte Obtener el id. de una tabla para obtener información sobre el id. de una tabla.

Solicitud:

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(00000000-0000-0000-0000-000000000002)"
}

Respuesta:

HTTP/1.1 204 No Content
OData-EntityId: [Organization URI]/api/data/v9.2/catalogassignments(00000000-0000-0000-0000-000000000003)

Uso del SDK para .NET

El siguiente código muestra la creación de una jerarquía de catálogo y una asignación de catálogo en una solución con UniqueName: ContosoCustomerManagement.

Nota

Utilice el parámetro opcional SolutionUniqueName con la Clase CreateRequest para crear los registros en el contexto de esa solución. Más información: Pasar parámetros opcionales con una solicitud

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;

Crear catálogos y asignaciones de catálogos editando archivos de soluciones

Dentro de un archivo de solución, puede editar los archivos para crear catálogos y asignaciones de catálogos.

Utilice la Herramienta SolutionPackager para extraer una solución en archivos que se pueden administrar en el control de código de origen. A continuación, puede editar los archivos. A continuación, puede utilizar SolutionPackager para volver a empaquetar los archivos extraídos en una solución. Más información : Control de código fuente con archivos de solución

Sugerencia

Cree algunos catálogos y asignaciones de catálogos en una solución, luego exporte y extraiga la solución para ver algunos ejemplos.

Asegúrese de que está utilizando la última versión del Paquete Microsoft.CrmSdk.CoreTools NuGet

Crear un catálogo con archivos de solución

Dentro de una solución, todos los catálogos estarán dentro de una carpeta catalogs. Puede crear, modificar o eliminar catálogos editando las carpetas y archivos en esta carpeta e importando la solución después de que se haya empaquetado usando el empaquetador de soluciones.

Cada catálogo se incluirá en una carpeta que coincida con el uniquename del catálogo, como contoso_CustomerManagement.

Dentro de la carpeta hay un archivo catalog.xml que contiene la definición del catálogo.

Por ejemplo:

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

El atributo catalog del elemento uniquename debe coincidir con el nombre de la carpeta que contiene el archivo.

El elemento catalog incluye estos elementos:

Elemento Descripción
description Tiene un atributo default con el valor de la descripción predeterminada.
Contiene uno o más elementos label con atributos para description y languagecode cuando se definen varios idiomas.
displayname Tiene un atributo default con el valor del nombre para mostrar predeterminado.
Contiene uno o más elementos label con atributos para description y languagecode cuando se definen varios idiomas.
iscustomizable Si el catálogo es personalizable. 0 = false, 1 = true.
name El nombre del catálogo.

Si el catálogo representa una categoría, la relación con el catálogo principal se incluye mediante un elemento parentcatalogid que contiene un elemento uniquename que contiene el nombre exclusivo del catálogo principal.

Por ejemplo:

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

Crear una CatalogAssignment con archivos de solución

Dentro de una solución, en la carpeta Assets encontrará un archivo catalogassignments.xml. Todas las asignaciones del catálogo se incluyen en el archivo. Puede crear o modificar asignaciones de catálogos editando este archivo e importando la solución después de que se haya empaquetado usando el empaquetador de soluciones.

Por ejemplo:

<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 elemento catalogassignment tiene estos atributos:

Atributo Descripción
catalogid.uniquename Nombre único del sub-catálogo para el que es la asignación de catálogo.
objecttypeid Tipo del objeto. Los valores válidos son:
entity
customapi
workflow

Dependiendo de objectypeid, cada elemento catalogassignment debe tener uno de estos atributos correspondientes:

Atributo Descripción
object.uniquename Nombre único de la API personalizada.
object.logicalname El nombre lógico de la entidad.
object.workflowid El valor de identificación único de la acción del proceso personalizado.

El elemento catalogassignment incluye estos elementos:

Elemento Descripción
iscustomizable Si la asignación de catálogo es personalizable. 0 = false, 1 = true.
name Nombre de la asignación de catálogo

Consulte también

Eventos de negocio de Microsoft Dataverse
Crear un registro de entidad usando la API web
Recuperar un registro de entidad usando la API web
Crear entidades con SDK para .NET
Recuperar un registro de entidad usando SDK para .NET

Nota

¿Puede indicarnos sus preferencias de idioma de documentación? Realice una breve encuesta. (tenga en cuenta que esta encuesta está en inglés)

La encuesta durará unos siete minutos. No se recopilan datos personales (declaración de privacidad).