Nota:
El acceso a esta página requiere autorización. Puede intentar iniciar sesión o cambiar directorios.
El acceso a esta página requiere autorización. Puede intentar cambiar los directorios.
Importante
Esta característica está actualmente en versión preliminar. Los Términos de uso complementarios para las versiones preliminares de Microsoft Azure incluyen términos legales adicionales que se aplican a Azure características que están en versión beta, en versión preliminar o que aún no se han publicado en disponibilidad general.
En este tutorial, aprenderá a interactuar mediante programación con Microsoft Purview mediante GraphQL API. Para obtener más información sobre GraphQL en general, consulte esta introducción a GraphQL.
El uso de GraphQL es similar al uso de las API REST, ya que se envía una carga JSON a un punto de conexión de servicio. Sin embargo, GraphQL nos permite devolver información completa en una sola captura, lo que elimina la necesidad de varias llamadas API.
GraphQL también usa la captura de datos declarativos. La captura declarativa de datos es útil para la captura selectiva en campos como laentidad relacionada con eltérmino/ de clasificación/ vinculada a la entidad original. Al usar GraphQL con estos patrones de consulta, podemos optimizar la captura de bases de datos back-end y la transmisión de datos. Un buen ejemplo es "Obtener entidad con entidades relacionadas filtradas, separadas por alias".
Con su característica de introspección, GraphQL API se vuelve autodescriptiva, lo que permite a los clientes recuperar detalles de esquema, como consultas disponibles, tipos y parámetros de consulta. Más información sobre la introspección.
Requisitos previos
Si no tiene una suscripción Azure, cree una cuenta gratuita antes de empezar.
Debe tener una cuenta de Microsoft Purview existente. Si no lo hace, consulte el inicio rápido para crear una cuenta de Microsoft Purview.
Para establecer un token de portador y llamar a cualquier API, consulte la documentación sobre cómo autenticar las API para Microsoft Purview.
Punto de conexión de GraphQL
Para todas las solicitudes, puede enviar una POST solicitud al siguiente punto de conexión:
POST https://{{endpoint}}/datamap/api/graphql
- Si usa el nuevo portal de Microsoft Purview, el valor {{endpoint}} es:
api.purview-service.microsoft.com. - Si usa el portal de gobernanza de Microsoft Purview clásico, el valor {{endpoint}} es:
{your_purview_account_name}.purview.azure.com.
Consulta básica
Entidad: lista por guides
query {
entities(where: { guid: ["<guid1>", "<guid2>"] }) { #Values in the array are combined as a logical-OR.
guid
createTime
updateTime
typeName
attributes
name
qualifiedName
description
}
}
Ejemplo de respuesta:
{
"data": {
"entities": [
{
"guid": "9fb74c11-ac48-4650-95bc-760665c5bd92",
"createTime": 1553072455110,
"updateTime": 1553072455110,
"typeName": "azure_storage_account",
"attributes": {
"qualifiedName": "https://exampleaccount.core.windows.net",
"name": "ExampleStorageAccount",
},
"name": "ExampleStorageAccount",
"qualifiedName": "https://exampleaccount.core.windows.net",
"description": "Example Storage Account"
}
]
}
}
Consulta de entidades por tipo y nombre completo
query {
entities(
where: {
type: { typeName: ["<entityType1>", "<entityType2>"] }
qualifiedName: { in: ["<qualifiedName1>", "<qualifiedName2>"] }
}
) {
guid
typeName
qualifiedName
attributes
}
}
El operador in se usa para consultar varios nombres completos.
Los operadores posibles podrían ser exists|eq|ne|in|nin|gt|ge|lt|le. Puede encontrar más detalles del esquema del servidor con introspección.
Captura de datos declarativos
Obtener entidad con campos seleccionados
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
businessAttributes
qualifiedName
}
}
Obtener entidad con todos los campos
query {
entities(where: { guid: "<guid>" }) {
guid
createTime
createdBy
updateTime
updatedBy
lastModifiedTS
typeName
attributes
businessAttributes
collectionId
customAttributes
hierarchyInfo {
...hierarchyInfoFields
}
labels
sensitivityLabel {
...sensitivityLabelFields
}
source
sourceDetails
qualifiedName
name
description
displayName
userDescription
classifications {
...classificationFields
}
relatedEntities {
...relatedEntitiesFields
}
assignedTerms {
...assignedTermsFields
}
}
}
Obtención de una entidad con clasificaciones
- con todas las clasificaciones
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
classifications {
typeName
attributes
}
}
}
- con clasificaciones filtradas
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
classifications(where: { type: { typeName: "<classificationType>" } }) {
typeName
attributes
}
}
}
Obtener entidad con entidades relacionadas
- con todas las entidades relacionadas
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
relatedEntities {
relationshipAttributeName
relationship {
guid
typeName
attributes
}
entity {
guid
typeName
qualifiedName
attributes
}
}
}
}
: con entidades relacionadas filtradas
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
relatedEntities(where: { relationshipAttributeName: "<relAttrName1>" }) {
entity {
guid
typeName
qualifiedName
attributes
}
}
}
}
- con entidades relacionadas filtradas, separadas por alias
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
alias1: relatedEntities(where: { relationshipAttributeName: "<relAttrName1>" }) {
entity {
guid
typeName
attributes
}
}
alias2: relatedEntities(where: { relationshipAttributeName: "<relAttrName2>" }) {
entity {
guid
typeName
attributes
}
}
}
}
Obtención de la entidad con términos del glosario
- con todos los términos del glosario
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
assignedTerms {
confidence
createdBy
description
expression
steward
source
status
term {
qualifiedName
name
shortDescription
longDescription
}
}
}
}
- con términos de glosario filtrados
query {
entities(where: { guid: "<guid>" }) {
guid
typeName
attributes
assignedTerms {
confidence
createdBy
description
expression
steward
source
status
term {
qualifiedName
name
shortDescription
longDescription
}
}
}
}
Filtrado (versión preliminar)
El rendimiento de la coincidencia exacta para "GUID" y "Qualified-Name" se garantiza en los ejemplos proporcionados en la sección "consultas básicas". Sin embargo, hay algunas limitaciones para otros patrones de filtrado:
- Filtrado por campos no indexados: los campos distintos del GUID & nombre completo no están indexados actualmente (como ejemplos en la sección "Filtro simple"). El filtrado de campos no indexados sin criterios en GUID/Nombre completo dará lugar a un examen de tabla y podría provocar problemas de rendimiento en grandes conjuntos de datos.
- Filtrado anidado: de forma similar a los campos no indizados, el filtrado anidado puede provocar exámenes de tabla, lo que puede provocar problemas de rendimiento en grandes conjuntos de datos. Por ejemplo, buscar una entidad con una clasificación vinculada, un término o una entidad relacionada.
A pesar de estas limitaciones, este patrón de llamada es superior al filtrado del lado cliente y actualmente lo usa nuestro cliente interno.
Filtro simple
Consulta de entidades por tipo y atributos del sistema
query {
entities(
where: {
type: { typeName: "<entityType>" }
name: { eq: "<value>" }
createTime: { timerange: LAST_7D }
updateTime: { gt: "<timestamp>" }
}
) {
guid
typeName
qualifiedName
attributes
}
}
Consulta de entidades por tipo y atributos
query {
entities(
where: {
type: { typeName: "<entityType>" }
attribute: { field: "<attrName>",operator: eq, value: "<attrValue>" }
}
) {
guid
typeName
qualifiedName
attributes
}
}
Consulta de entidades por tipo y atributos empresariales
query {
entities(
where: {
type: { typeName: "<entityType>" }
businessAttribute: { field: "<BusinessMetadataName>.<BusinessAttributeName>", operator: eq, value: "<BizAttrValue>" }
}
) {
guid
typeName
qualifiedName
attributes
}
}
Consulta de entidades por colección
Actualmente, este patrón de consulta no se admite para los conjuntos de subassets.
query {
entities(
where: {
type: { typeName: "<entityType>" }
collectionID: "<collectionId>"
}
) {
guid
typeName
qualifiedName
attributes
}
}
Combinación de filtros
Las claves de un objeto (mapa) se combinan como un AND lógico.
query {
entities(
where: {
type: { typeName: "<entityType>" }
or: [
{
and: [
{ attribute: { field: "<attrName1>", value: "<attrValue1>" } }
{ attribute: { field: "<attrName2>", value: "<attrValue2>" } }
]
}
{
not: {
businessAttribute: {
field: "<BusinessMetadataName>.<BusinessAttributeName>", value: "<BizAttrValue>"
}
}
}
]
}
) {
guid
typeName
qualifiedName
attributes
}
}
Filtro anidado
Actualmente, este patrón de consulta no se admite para los conjuntos de subassets.
Consulta de entidad por clasificación
query {
entities(
where: {
classification: { type: { typeName: "<classificationType>", includeSubTypes: true } }
}
) {
guid
typeName
qualifiedName
attributes
}
}
Consulta de entidad por entidad relacionada
query {
entities(
where: {
relatedEntity: {
relationshipAttributeName: "<relAttrName>"
entity: {
type: { typeName: "<entityType>" }
}
}
}
) {
guid
typeName
qualifiedName
attributes
}
}
Consulta de entidad por términos del glosario
query {
entities(
where: {
assignedTerm: {
term: {
qualifiedName: { eq: "<termName>" }
}
}
}
) {
guid
typeName
qualifiedName
attributes
}
}
Otras consultas
Obtener relación
query {
relationships(where: { guid: "<guid>" }) {
guid
typeName
attributes
end1 {
guid
typeName
qualifiedName
attributes
}
end2 {
guid
typeName
qualifiedName
attributes
}
}
}
Ejemplo de respuesta:
{
"data": {
"relationships": [
{
"guid": "...",
"typeName": "ExampleRelationship",
"attributes": {},
"end1": {
"guid": "...",
"typeName": "column",
"qualifiedName": "...",
"attributes": {}
},
"end2": {
"guid": "...",
"typeName": "column",
"qualifiedName": "...",
"attributes": {}
}
}
]
}
}
Linaje
Obtención de conjuntos de datos con conjuntos de datos de nivel inferior
Esta consulta devuelve conjuntos de datos de nivel inferior a 2 grados.
query {
entities(where: { guid: "<guid>" }) {#dataset
guid
typeName
qualifiedName
relatedEntities(where: { relationshipAttributeName: "inputToProcesses" }) {
entity {#process
guid
typeName
relatedEntities(where: { relationshipAttributeName: "outputs" }) {
entity {#dataset
guid
typeName
qualifiedName
relatedEntities(where: { relationshipAttributeName: "inputToProcesses" }) {
entity {#process
guid
typeName
qualifiedName
relatedEntities(where: { relationshipAttributeName: "outputs" }) {
entity {#dataset
guid
typeName
qualifiedName
}
}
}
}
}
}
}
}
}
}
Ejemplo de respuesta:
{
"data": {
"entities": [
{
"guid": "...",
"typeName": "Dataset",
"qualifiedName": "...",
"relatedEntities": [
{
"entity": {
"guid": "...",
"typeName": "Process",
"relatedEntities": [
{
"entity": {
"guid": "...",
"typeName": "Dataset",
"qualifiedName": "...",
"relatedEntities": [
{
"entity": {
"guid": "...",
"typeName": "Process",
"relatedEntities": [
{
"entity": {
"guid": "...",
"typeName": "Dataset",
"qualifiedName": "..."
}
}
]
}
}
]
}
}
]
}
}
]
}
]
}
}
Limitaciones
Limitación de la profundidad de captura de consultas:
Las consultas están limitadas por la profundidad de la consulta. La profundidad máxima es 5. Por ejemplo, se producirá un error en la consulta siguiente:
query {
entities { #depth 1
relatedEntities { #depth 2
entity {
relatedEntities { #depth 3
entity {
assignedTerms{ #depth 4
term {
classifications { #depth 5
...
}
}
}
relatedEntities { #depth 4
entity {
assignedTerms{ #depth 5
term {
classifications { #depth 6
...
}
}
}
}
}
}
}
}
}
}
}
Limitación del costo de captura en tiempo de ejecución:
Las consultas están restringidas por el costo de la ejecución de consultas. El costo máximo permitido se establece en 100 unidades.
El costo de captura de ejecución se calcula cada vez que se pretende recuperar entidades relacionadas, términos asignados o clasificaciones de una entidad o término determinados.
Ejemplo
Considere un escenario en el que se consultan tres entidades, cada una con dos entidades relacionadas. El cálculo de costos sería el siguiente:
- Una unidad para la consulta raíz
- Tres unidades para cada entidad de nivel 1
Por lo tanto, el costo total de esta consulta sería 1 (root query) + 3 (level-1 entities) = 4.
Filtrado del rendimiento
El filtrado es actualmente una versión preliminar y tiene algunas limitaciones. Consulte filtrado para obtener más información.
Las consultas de GraphQL comienzan con una consulta raíz que recupera los nodos de nivel superior. A continuación, captura de forma recursiva los nodos relacionados.
El rendimiento de una consulta anidada viene determinado principalmente por la consulta raíz porque los nodos relacionados se capturan desde un punto de partida conocido, similar a una clave externa en SQL.
Para optimizar el rendimiento, es fundamental evitar consultas raíz con caracteres comodín que podrían desencadenar un examen de tabla en los nodos de nivel superior.
Por ejemplo, la siguiente consulta podría provocar problemas de rendimiento en conjuntos de datos grandes porque el name campo no está indexado:
query {
entities(where: { name: { eq: "<value>" } }) {
guid
typeName
attributes
relatedEntities {
entity {
guid
typeName
attributes
}
}
}
}
Para evitar estos problemas de rendimiento, asegúrese de aplicar un filtro en guid o qualifiedName.