Compartilhar via

Consultas em várias tabelas

Ao usar colunas de tipo de pesquisa para várias tabelas, às vezes chamadas pesquisas polimórficas, você pode utilizar uma tabela específica que possui várias relações um-para-muitos (1:N) com outras tabelas no ambiente. Uma única coluna de tipo de pesquisa pode se referir a várias outras tabelas. Um valor de pesquisa enviado para a coluna do tipo multi-tabela corresponde a um registro em qualquer uma das tabelas relacionadas. Você pode criar pesquisas de várias tabelas com tabelas locais e tabelas virtuais como tabelas referenciadas.

Microsoft Dataverse atualmente inclui tipos de várias tabelas como tipos estáticos, como Customer, que se conecta às tabelas Account e Contact. Ao usar pesquisas de várias tabelas, você pode definir outras pesquisas de várias tabelas que precisar.

Observação

Você pode criar e modificar pesquisas personalizadas de várias tabelas por meio do SDK para .NET ou API Web do Dataverse. O suporte interativo à interface do usuário estará disponível em uma versão futura.

Exemplo: o exemplo de pesquisa de várias tabelas da API Web (PowerShell) contém o código de exemplo que demonstra o exemplo apresentado neste artigo.

Para recuperar informações sobre tabelas relacionadas com uma coluna de pesquisa, incluindo pesquisas de várias tabelas, use um dos seguintes métodos: recuperar a propriedade de pesquisa ou expandir a propriedade de navegação com valor único.

Recuperar a propriedade de pesquisa

Cada coluna de pesquisa tem uma propriedade de pesquisa correspondente que você pode recuperar usando a opção $select de consulta. Essas propriedades seguem a convenção de nomenclatura: _<name>_value. <name> é o nome lógico da coluna de pesquisa. O valor da propriedade de pesquisa é o identificador exclusivo do registro relacionado, se houver.

Para uma pesquisa de várias tabelas, a ID exclusiva não é valiosa, a menos que você saiba a qual tabela ela se aplica. Ao recuperar dados de qualquer coluna de pesquisa, você pode aplicar as seguintes preferências de anotação OData. Essas opções de preferência são especialmente úteis com uma pesquisa de várias tabelas porque fornecem mais dados do registro relacionado e informações sobre de qual tabela os dados vêm.

Annotation Descrição
OData.Community.Display.V1.FormattedValue Retorna o valor da coluna de nome primário para o registro atualmente definido nesta coluna.
Microsoft.Dynamics.CRM.associatednavigationproperty Retorna o nome da propriedade de navegação de valor único que dá suporte ao registro atualmente definido nesta coluna.
Microsoft.Dynamics.CRM.lookuplogicalname Retorna o nome lógico da tabela para o registro atualmente definido nesta coluna.

Observação

Use as propriedades de pesquisa para recuperar o valor formatado e os metadados de suporte necessários para expandir a propriedade de navegação com valor único para obter mais informações.

Saiba mais sobre como recuperar dados de propriedades de referência.

Expandir a propriedade de navegação com valor único

Quando você cria uma pesquisa de várias tabelas, cada tabela requer uma relação um-para-muitos separada. Cada relação adiciona uma propriedade de navegação de valor único distinta.

O nome dessa propriedade de navegação com valor único é armazenado na propriedade OneToManyRelationshipMetadata.ReferencingEntityNavigationPropertyName . Um erro comum é quando as pessoas tentam adivinhar o valor dessa propriedade que diferencia maiúsculas de minúsculas. Há três maneiras de determinar definitivamente o nome correto desta propriedade de navegação:

Ao consultar a tabela, use a opção $expand de consulta com a propriedade de navegação de valor único para incluir a tabela relacionada. Saiba mais sobre como unir tabelas relacionadas usando a opção de consulta OData$expand.

Exemplo

Suponha que você esteja hospedando mídia para usuários em uma biblioteca. Você tem muitos objetos de mídia diferentes. Muitos deles têm o mesmo nome, mas estão em formatos diferentes, como livros, áudio e vídeo.

Neste exemplo, três tabelas dão suporte a cada tipo específico de mídia:

  • sample_Book inclui sample_name e sample_callnumber colunas.
  • sample_Audio inclui sample_name e sample_audioformat colunas.
  • sample_Video inclui sample_name e sample_videoformat colunas.

A sample_Media tabela tem uma consulta de várias tabelas com o nome sample_MediaPolymorphicLookup do esquema. Você pode definir a coluna de pesquisa para se referir a registros em qualquer uma das três tabelas de mídia específicas.

Tabela sample_Book

A sample_Book tabela é a primeira das três tabelas relacionadas. Essa consulta simples recupera os dois registros encontrados nesta tabela.

GET [Organization URI]/api/data/v9.2/sample_books?$select=sample_name,sample_callnumber
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Este exemplo mostra o corpo JSON da resposta:

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sample_books(sample_name,sample_callnumber)",
   "value": [
      {
         "@odata.etag": "W/\"171704230\"",
         "sample_callnumber": "ww-3452 ",
         "sample_bookid": "00000000-0000-0000-0000-000000000001",
         "sample_name": "Content1"
      },
      {
         "@odata.etag": "W/\"171704235\"",
         "sample_callnumber": "a4e-87hw",
         "sample_bookid": "00000000-0000-0000-0000-000000000005",
         "sample_name": "Content2"
      }
   ]
}

Tabela sample_Audio

A sample_Audio tabela é a segunda das três tabelas relacionadas. Essa consulta simples recupera os dois registros nesta tabela.

GET [Organization URI]/api/data/v9.2/sample_audios?$select=sample_name,sample_audioformat
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Este exemplo mostra o corpo JSON da resposta:

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sample_audios(sample_name,sample_audioformat)",
   "value": [
      {
         "@odata.etag": "W/\"171704242\"",
         "sample_audioid": "00000000-0000-0000-0000-000000000002",
         "sample_audioformat": "mp4",
         "sample_name": "Content1"
      },
      {
         "@odata.etag": "W/\"171704246\"",
         "sample_audioid": "00000000-0000-0000-0000-000000000004",
         "sample_audioformat": "wma",
         "sample_name": "Content3"
      }
   ]
}

Tabela sample_Video

A sample_Video tabela é a terceira das três tabelas relacionadas. Essa consulta simples recupera os dois registros nesta tabela.

GET [Organization URI]/api/data/v9.2/sample_videos?$select=sample_name,sample_videoformat
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json

Este exemplo mostra o corpo JSON da resposta:

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sample_videos(sample_name,sample_videoformat)",
   "value": [
      {
         "@odata.etag": "W/\"171704254\"",
         "sample_name": "Content2",
         "sample_videoformat": "avi",
         "sample_videoid": "00000000-0000-0000-0000-000000000006"
      },
      {
         "@odata.etag": "W/\"171704250\"",
         "sample_name": "Content3",
         "sample_videoformat": "wmv",
         "sample_videoid": "00000000-0000-0000-0000-000000000003"
      }
   ]
}

Tabela sample_Media

Esta tabela tem a coluna de pesquisa de várias tabelas com nome de esquema sample_MediaPolymorphicLookup e nome lógico sample_mediapolymorphiclookup.

Para fins desta demonstração, esta tabela contém apenas quatro registros relacionados aos registros de suporte:

sample_name Valor sample_mediapolymorphiclookup Tipo de sample_mediapolymorphiclookup
Objeto de mídia um 00000000-0000-0000-0000-000000000001 sample_book
Objeto de mídia Dois 00000000-0000-0000-0000-000000000002 sample_audio
Objeto de mídia, três 00000000-0000-0000-0000-000000000003 sample_video
Objeto de mídia Quatro 00000000-0000-0000-0000-000000000004 sample_audio

Usando a sample_Media tabela, este exemplo de consulta:

  • Seleciona a propriedade de pesquisa _sample_mediapolymorphiclookup_value na opção de consulta $select para a coluna de pesquisa sample_mediapolymorphiclookup. Usando as preferências OData.Community.Display.V1.FormattedValue, Microsoft.Dynamics.CRM.associatednavigationproperty e Microsoft.Dynamics.CRM.lookuplogicalnameodata.include-annotations, você obtém esses valores com cada registro.
  • Expande três propriedades de navegação de valor único, uma para cada tabela relacionada. Para cada propriedade de navegação expandida, a coluna de nome primário (sample_name) é selecionada, bem como o respectivo valor de coluna personalizado: sample_callnumber, , sample_audioformat. sample_videoformat

Observação

Apenas uma das três navegações de valor único expandida pode ter dados. Os três serão nulos se a coluna de pesquisa não estiver definida.

Essas operações demonstram como os registros de tabela estão relacionados por meio da sample_MediaPolymorphicLookup coluna de pesquisa.

Solicitação

GET [Organization URI]
/api/data/v9.2/sample_medias
?$select=sample_name,_sample_mediapolymorphiclookup_value
&$expand=sample_MediaPolymorphicLookup_sample_book(
    $select=sample_name,sample_callnumber),
sample_MediaPolymorphicLookup_sample_audio(
    $select=sample_name,sample_audioformat),
sample_MediaPolymorphicLookup_sample_video(
    $select=sample_name,sample_videoformat)
Content-Type: application/json; charset=utf-8
OData-MaxVersion: 4.0
OData-Version: 4.0
Accept: application/json
Prefer: odata.include-annotations="OData.Community.Display.V1.FormattedValue,Microsoft.Dynamics.CRM.associatednavigationproperty,Microsoft.Dynamics.CRM.lookuplogicalname"

Observação

Para legibilidade, a URL é mostrada em várias linhas. Ao fazer a solicitação, remova todas as quebras de linha e o espaço em branco para que a URL seja uma única cadeia de caracteres contínua.

Resposta

Quando você define essas opções de consulta e cabeçalhos de preferência, o corpo da resposta contém o seguinte JSON:

{
   "@odata.context": "[Organization URI]/api/data/v9.2/$metadata#sample_medias(sample_name,_sample_mediapolymorphiclookup_value,sample_MediaPolymorphicLookup_sample_book(sample_name),sample_MediaPolymorphicLookup_sample_audio(sample_name,sample_audioformat),sample_MediaPolymorphicLookup_sample_video(sample_name))",
   "value": [
      {
         "@odata.etag": "W/\"171704264\"",
         "sample_mediaid": "00000000-0000-0000-0000-000000000007",
         "sample_name": "Media Object One",
         "_sample_mediapolymorphiclookup_value@OData.Community.Display.V1.FormattedValue": "Content1",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "sample_MediaPolymorphicLookup_sample_book",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.lookuplogicalname": "sample_book",
         "_sample_mediapolymorphiclookup_value": "00000000-0000-0000-0000-000000000001",
         "sample_MediaPolymorphicLookup_sample_book": {
            "sample_bookid": "00000000-0000-0000-0000-000000000001",
            "sample_name": "Content1",
            "sample_callnumber": "ww-3452"
         },
         "sample_MediaPolymorphicLookup_sample_audio": null,
         "sample_MediaPolymorphicLookup_sample_video": null
      },
      {
         "@odata.etag": "W/\"171704268\"",
         "sample_mediaid": "00000000-0000-0000-0000-000000000008",
         "sample_name": "Media Object Two",
         "_sample_mediapolymorphiclookup_value@OData.Community.Display.V1.FormattedValue": "Content1",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "sample_MediaPolymorphicLookup_sample_audio",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.lookuplogicalname": "sample_audio",
         "_sample_mediapolymorphiclookup_value": "00000000-0000-0000-0000-000000000002",
         "sample_MediaPolymorphicLookup_sample_book": null,
         "sample_MediaPolymorphicLookup_sample_audio": {
            "sample_audioid": "00000000-0000-0000-0000-000000000002",
            "sample_name": "Content1",
            "sample_audioformat": "mp4"
         },
         "sample_MediaPolymorphicLookup_sample_video": null
      },
      {
         "@odata.etag": "W/\"171704273\"",
         "sample_mediaid": "00000000-0000-0000-0000-000000000009",
         "sample_name": "Media Object Three",
         "_sample_mediapolymorphiclookup_value@OData.Community.Display.V1.FormattedValue": "Content3",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "sample_MediaPolymorphicLookup_sample_video",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.lookuplogicalname": "sample_video",
         "_sample_mediapolymorphiclookup_value": "00000000-0000-0000-0000-000000000003",
         "sample_MediaPolymorphicLookup_sample_book": null,
         "sample_MediaPolymorphicLookup_sample_audio": null,
         "sample_MediaPolymorphicLookup_sample_video": {            
            "sample_videoid": "00000000-0000-0000-0000-000000000003",
            "sample_name": "Content3",
            "sample_videoformat": "wmv"
         }
      },
      {
         "@odata.etag": "W/\"171704279\"",
         "sample_mediaid": "00000000-0000-0000-0000-000000000010",
         "sample_name": "Media Object Four",
         "_sample_mediapolymorphiclookup_value@OData.Community.Display.V1.FormattedValue": "Content3",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.associatednavigationproperty": "sample_MediaPolymorphicLookup_sample_audio",
         "_sample_mediapolymorphiclookup_value@Microsoft.Dynamics.CRM.lookuplogicalname": "sample_audio",
         "_sample_mediapolymorphiclookup_value": "00000000-0000-0000-0000-000000000004",
         "sample_MediaPolymorphicLookup_sample_book": null,
         "sample_MediaPolymorphicLookup_sample_audio": {
            "sample_audioid": "00000000-0000-0000-0000-000000000004",
            "sample_name": "Content3",
            "sample_audioformat": "wma"
         },
         "sample_MediaPolymorphicLookup_sample_video": null
      }
   ]
}

Definindo uma coluna de pesquisa de várias tabelas

Atualizar um registro para definir uma coluna de pesquisa polimórfica é exatamente como descrito em Associar a uma propriedade de navegação com valor único. Use o nome correto da propriedade de navegação com valor único. Esses nomes diferenciam maiúsculas de minúsculas.

Este exemplo mostra a atualização de um valor usando PATCH.

Solicitação

PATCH [Organization Uri]/api/data/v9.2/sample_medias(00000000-0000-0000-0000-000000000007) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "sample_MediaPolymorphicLookup_sample_book@odata.bind": "sample_books(00000000-0000-0000-0000-000000000001)"
}

Resposta

HTTP/1.1 204 NoContent
OData-Version: 4.0

Criar uma coluna de consulta de várias tabelas

Observação

O exemplo a seguir mostra como usar a API Web do Dataverse. Você também pode usar o SDK para .NET com as classes CreatePolymorphicLookupAttributeRequest e CreatePolymorphicLookupAttributeResponse.

Use a ação CreatePolymorphicLookupAttribute para criar uma pesquisa de várias tabelas. Este exemplo cria a coluna como parte de uma solução com o nome polymorphiclookupexamplesolution exclusivo usando o SolutionUniqueName parâmetro.

Solicitação

POST [Organization URI]/api/data/v9.2/CreatePolymorphicLookupAttribute HTTP/1.1
Consistency: Strong
Accept: application/json
OData-MaxVersion: 4.0
Authorization: Bearer [REDACTED]
OData-Version: 4.0

{
  "OneToManyRelationships": [
    {
      "ReferencedEntity": "sample_book",
      "SchemaName": "sample_media_sample_book",
      "ReferencingEntity": "sample_media"
    },
    {
      "ReferencedEntity": "sample_audio",
      "SchemaName": "sample_media_sample_audio",
      "ReferencingEntity": "sample_media",
      "CascadeConfiguration": {
        "Assign": "NoCascade",
        "Share": "NoCascade",
        "Delete": "RemoveLink",
        "Merge": "NoCascade",
        "Reparent": "NoCascade",
        "Unshare": "NoCascade"
      }
    },
    {
      "ReferencedEntity": "sample_video",
      "SchemaName": "sample_media_sample_video",
      "ReferencingEntity": "sample_media",
      "CascadeConfiguration": {
        "Assign": "NoCascade",
        "Share": "NoCascade",
        "Delete": "RemoveLink",
        "Merge": "NoCascade",
        "Reparent": "NoCascade",
        "Unshare": "NoCascade"
      }
    }
  ],
  "Lookup": {
    "AttributeTypeName": {
      "Value": "LookupType"
    },
    "SchemaName": "sample_MediaPolymorphicLookup",
    "Description": {
      "LocalizedLabels": [
        {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Polymorphic lookup that can reference a Book, Audio, or Video record",
          "LanguageCode": 1033
        }
      ],
      "@odata.type": "Microsoft.Dynamics.CRM.Label"
    },
    "AttributeType": "Lookup",
    "DisplayName": {
      "LocalizedLabels": [
        {
          "@odata.type": "Microsoft.Dynamics.CRM.LocalizedLabel",
          "Label": "Media",
          "LanguageCode": 1033
        }
      ],
      "@odata.type": "Microsoft.Dynamics.CRM.Label"
    },
    "@odata.type": "Microsoft.Dynamics.CRM.ComplexLookupAttributeMetadata"
  },
 "SolutionUniqueName": "polymorphiclookupexamplesolution"
}

A resposta a seguir contém um exemplo do ComplexType CreatePolymorphicLookupAttributeResponse. Ele contém a ID do atributo polimórfico e todas as relações criadas.

Resposta

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{
    "@odata.context":
      "http://<organization URL>/api/data/v9.2/$metadata#Microsoft.Dynamics.CRM.CreatePolymorphicLookupAttributeResponse",

    "RelationshipIds":[
        "77d4c6e9-0397-eb11-a81c-000d3a6cfaba",
        "7ed4c6e9-0397-eb11-a81c-000d3a6cfaba",
        "85d4c6e9-0397-eb11-a81c-000d3a6cfaba"
    ],

    "AttributeId":"d378dd3e-42f4-4bd7-95c7-0ee546c7de40"
}

Adicionar relação à coluna de pesquisa de várias tabelas existente

Adicionar uma relação a uma coluna de pesquisa de várias tabelas existente usando a API Web é semelhante à criação de qualquer nova relação um-para-muitos. Saiba como criar uma relação um-para-muitos usando a API Web. A diferença é que a propriedade OneToManyRelationshipMetadata.Lookup deve ter um SchemaName valor que corresponda à coluna de pesquisa polimórfica existente.

Remover uma relação de uma coluna existente de pesquisa em várias tabelas

Remover uma relação de uma coluna de pesquisa de várias tabelas existente usando a API Web é o mesmo que excluir qualquer relação um-para-muitos. Envie uma DELETE solicitação para o RelationshipDefinitions endpoint utilizando o valor da propriedade OneToManyRelationshipMetadata.MetadataId como chave.

Consulte também

Exemplo: exemplo de pesquisa de várias tabelas da API Web (PowerShell)
Usar a API Web com definições de tabela
Criar e atualizar relações de tabela
Consultar definições de tabela usando a API Web
Recuperar definições de tabela por nome ou MetadataId
Modelar tabelas e colunas usando a API Web
Exemplo de operações de esquema de tabela da API Web
Exemplo de operações de esquema de tabela de API Web (C#)

  • Last updated on