Exemplos de consulta OData
Observação
As tabelas do Customer Insights - Data também podem ser acessadas usando APIs do Dataverse. É recomendável usar as APIs do Dataverse para consultar dados do Customer Insights, pois elas oferecem uma filtragem mais extensa, mais taxa de transferência e menos latência. Para obter mais informações, consulte APIs do Dataverse para Customer Insights.
O Protocolo Open Data (OData) é um protocolo de acesso a dados baseado em protocolos importantes como HTTP. Ele usa metodologias comumente aceitas como REST para a Web. Há vários tipos de bibliotecas e ferramentas que podem ser usadas para consumir serviços OData.
Para ajudar a compilar as próprias implementações com base nas APIs do Dynamics 365 Customer Insights - Data, revise algumas consultas de exemplo mais solicitadas.
Modifique os exemplos de consulta para fazê-los funcionar nos ambientes de destino:
- {serviceRoot}:
https://api.ci.ai.dynamics.com/v1/instances/{instanceId}em que {instanceId} é o GUID do ambiente do Customer Insights - Data que você deseja consultar. A operação ListAllInstances permite que você encontre a {InstanceId} à qual tem acesso. - {CID}: GUID de um registro de cliente unificado. Exemplo:
ce759201f786d590bf2134bff576c369. - {AlternateKey}: identificador da chave primária de um registro de cliente em uma fonte de dados. Exemplo:
CNTID_1002 - {DSname}: cadeia de caracteres com o nome da tabela de uma fonte de dados ingerida no Customer Insights - Data. Exemplo:
Website_contacts. - {SegmentName}: cadeia de caracteres com o nome da tabela de saída de um segmento no Customer Insights - Data. Exemplo:
Male_under_40.
Customer
Consultas de exemplo para a tabela Cliente.
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| ID de cliente única | {serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}' |
|
| Chave alternativa | {serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} eq '{AlternateKey}' |
As chaves alternativas persistem na tabela de cliente unificado |
| Select | {serviceRoot}/data/Customer?$select=CustomerId,FullName&$filter=customerid eq '1' |
|
| Em | {serviceRoot}/data/Customer?$filter=CustomerId in ('{CID1}',’{CID2}’) |
|
| Chave Alternativa + In | {serviceRoot}/data/Customer?$filter={DSname_TableName_PrimaryKeyColumnName} in ('{AlternateKey}','{AlternateKey}') |
|
| Pesquisa | {serviceRoot}/data/Customer?$top=10&$skip=0&$search="string" |
Retorna os 10 principais resultados de uma cadeia de caracteres de pesquisa |
| Associação ao segmento | {serviceRoot}/data/Customer?select=*&$filter=IsMemberOfSegment('{SegmentName}')&$top=10 |
Retorna um número predefinido de linhas da tabela de segmentação. |
| Associação ao segmento para um cliente | {serviceRoot}/data/Customer?$filter=CustomerId eq '{CID}'&IsMemberOfSegment('{SegmentName}') |
Retorna o perfil do cliente se ele for um membro do determinado segmento |
Atividade unificada
Consultas de exemplo para a tabela UnifiedActivity:
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| Atividade de CID | {serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' |
Lista as atividades de um perfil de cliente específico |
| Período da atividade | {serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' and ActivityTime gt 2017-01-01T00:00:00.000Z and ActivityTime lt 2020-01-01T00:00:00.000Z |
Atividades de um perfil de cliente em um período |
| Tipo de atividade | {serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq '{CID}' and ActivityType eq '{ActivityName}' |
|
| Atividade por nome de exibição | {serviceRoot}/data/UnifiedActivity$filter=CustomerId eq ‘{CID}’ and ActivityTypeDisplay eq ‘{ActivityDisplayName}’ |
|
| Classificação de atividades | {serviceRoot}/data/UnifiedActivity?$filter=CustomerId eq ‘{CID}’ & $orderby=ActivityTime asc |
Classificar atividades em ordem crescente ou decrescente |
| Todas as atividades e medidas para um cliente | {serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId eq '{CID}' |
Atividades e medidas são pares de chave/valor adicionais no perfil do cliente retornado |
Gerenciar fluxos de trabalho
Consultas de amostra relacionadas a processos no Customer Insights - Data, como atualizar uma fonte de dados, unificar dados ou obter o status de um trabalho de unificação.
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| Obter IDs da fonte de dados | {serviceRoot}/manage/datasources/v2 |
Retorna todas as fontes de dados no ambiente. Na resposta, você pode verificar o 'friendlyName' para uma fonte de dados específica e, em seguida, usar o 'dataSourceId'. |
| Atualizar uma fonte de dados | {serviceRoot}/manage/workflows/main/jobs?operationType=Ingestion&identifiers='{dataSourceId}'&forceRunRequested=true |
Use o 'dataSourceId' da resposta acima para atualizar uma fonte de dados. Esta é uma solicitação POST. |
| Executar uma atualização completa | {serviceRoot}/manage/workflows/main/jobs?operationType=all&forceRunRequested=true |
Automatiza todos os processos no ambiente. Esta é uma solicitação POST. |
| Obter status dos processos | {serviceRoot}/manage/workflows/main/jobs |
Outros exemplos
Consultas de exemplo para outras tabelas:
| Tipo de consulta | Exemplo | Observação |
|---|---|---|
| Medidas de CID | {serviceRoot}/data/Customer_Measure?$filter=CustomerId eq '{CID}' |
|
| Marcas enriquecidas de CID | {serviceRoot}/data/BrandShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}' |
|
| Interesses enriquecidos de CID | {serviceRoot}/data/InterestShareOfVoiceFromMicrosoft?$filter=CustomerId eq '{CID}' |
|
| Na Cláusula + Expandir | {serviceRoot}/data/Customer?$expand=UnifiedActivity,Customer_Measure&$filter=CustomerId in ('{CID}', '{CID}') |
Limitações
A API do Customer Insights retorna um máximo de 100 objetos por padrão. Você pode analisar mais de 100 objetos retornados usando técnicas de paginação padrão. Alternativamente, você pode exportar seus dados.
As seguintes consultas não são compatíveis:
-
$filterem tabelas de origem ingeridas. Você só pode executar consultas $filter em tabelas do sistema criadas pelo Customer Insights - Data. -
$expanda partir de uma consulta$search. Por exemplo:Customer?$expand=UnifiedActivity$top=10&$skip=0&$search="corey". -
$expanda partir de$select, se apenas um subconjunto de atributos for selecionado. Por exemplo:Customer?$select=CustomerId,FullName&$expand=UnifiedActivity&$filter=CustomerId eq '{CID}'. -
$expandmarca enriquecida ou afinidades de interesse para um determinado cliente. Por exemplo:Customer?$expand=BrandShareOfVoiceFromMicrosoft&$filter=CustomerId eq '518291faaa12f6d853c417835d40eb10'. - Consulte tabelas de saída do modelo de previsão por meio de chave alternativa. Por exemplo:
OOBModelOutputTable?$filter=HotelCustomerID eq '{AK}'.
-