Concetti per sviluppatori del Catalogo dati di AzureAzure Data Catalog developer concepts

Catalogo dati di Microsoft Azure è un servizio cloud completamente gestito che offre funzionalità di individuazione dell'origine dati e di crowdsourcing dei metadati dell'origine dati.Microsoft Azure Data Catalog is a fully managed cloud service that provides capabilities for data source discovery and for crowdsourcing data source metadata. Gli sviluppatori possono usare il servizio tramite le API REST.Developers can use the service via its REST APIs. La comprensione dei concetti implementati nel servizio è importante per gli sviluppatori al fine di una perfetta integrazione con il Catalogo dati di Azure.Understanding the concepts implemented in the service is important for developers to successfully integrate with Azure Data Catalog.

Concetti chiaveKey concepts

Il modello concettuale di Azure Data Catalog è basato su quattro concetti chiave: il catalogo, gli utenti, gli asset e le annotazioni.The Azure Data Catalog conceptual model is based on four key concepts: The Catalog, Users, Assets, and Annotations.

concetto

Figura 1. Modello concettuale semplificato del Catalogo dati di AzureFigure 1 - Azure Data Catalog simplified conceptual model

CatalogoCatalog

Il catalogo è il contenitore di livello principale per tutti i metadati archiviati da un'organizzazione.A Catalog is the top-level container for all the metadata an organization stores. Per ogni account Azure è consentito un solo catalogo.There is one Catalog allowed per Azure Account. I cataloghi sono legati a una sottoscrizione di Azure. Anche se un account può avere più sottoscrizioni, per un determinato account Azure è possibile creare un solo catalogo.Catalogs are tied to an Azure subscription, but only one Catalog can be created for any given Azure account, even though an account can have multiple subscriptions.

Un catalogo contiene utenti e asset.A catalog contains Users and Assets.

UtentiUsers

Gli utenti sono entità di sicurezza autorizzati a eseguire azioni nel catalogo, ad esempio a fare ricerche nel catalogo, aggiungere, modificare o rimuovere elementi e così via.Users are security principals that have permissions to perform actions (search the catalog, add, edit or remove items, etc.) in the Catalog.

Diversi sono i ruoli disponibili che un utente può avere.There are several different roles a user can have. Per altre informazioni sui ruoli, vedere la sezione Ruoli e autorizzazione.For information on roles, see the section Roles and Authorization.

È possibile aggiungere singoli utenti e gruppi di sicurezza.Individual users and security groups can be added.

Il Catalogo dati di Azure usa Azure Active Directory per la gestione delle identità e degli accessi.Azure Data Catalog uses Azure Active Directory for identity and access management. Ogni utente del catalogo deve essere un membro di Active Directory per l'account.Each Catalog user must be a member of the Active Directory for the account.

assetAssets

Il catalogo contiene gli asset di dati.A Catalog contains data assets. asset rappresentano l'unità di granularità gestita dal catalogo.Assets are the unit of granularity managed by the catalog.

La granularità di un asset varia a seconda dell'origine dati.The granularity of an asset varies by data source. Per database Oracle o SQL Server un asset può essere una tabella o una vista.For SQL Server or Oracle Database, an asset can be a Table or a View. Per SQL Server Analysis Services un asset può essere una misura, una dimensione o un indicatore di prestazioni chiave (KPI).For SQL Server Analysis Services, an asset can be a Measure, a Dimension, or a Key Performance Indicator (KPI). Per SQL Server Reporting Services un asset è un report.For SQL Server Reporting Services, an asset is a Report.

L'asset è l'elemento che si aggiunge o si rimuove da un catalogo.An Asset is the thing you add or remove from a Catalog. È l'unità di risultato ottenuto dalla ricerca.It is the unit of result you get back from Search.

L' asset è composto dal relativo nome, dal percorso, dal tipo e dalle annotazioni che lo descrivono ulteriormente.An Asset is made up from its name, location, and type, and annotations that further describe it.

annotazioniAnnotations

Le annotazioni sono elementi che rappresentano i metadati relativi agli asset.Annotations are items that represent metadata about Assets.

Descrizioni, tag, schemi, documentazione e così via sono esempi di annotazioni. Un elenco completo dei tipi di annotazione e di asset è disponibile nella sezione Modello a oggetti asset.Examples of annotations are description, tags, schema, documentation, etc. A full list of the asset types and annotation types are in the Asset Object model section.

Annotazioni crowdsourcing e prospettiva dell'utente (molteplicità di opinione)Crowdsourcing annotations and user perspective (multiplicity of opinion)

Un aspetto fondamentale del Catalogo dati di Azure è il supporto crowdsourcing dei metadati nel sistema.A key aspect of Azure Data Catalog is how it supports the crowdsourcing of metadata in the system. A differenza dell'approccio wiki, dove è presente una sola opinione e l'ultima scrittura prevale, il modello Catalogo dati di Azure consente a più opinioni di convivere affiancate nel sistema.As opposed to a wiki approach – where there is only one opinion and the last writer wins – the Azure Data Catalog model allows multiple opinions to live side by side in the system.

Questo approccio riflette il mondo reale dei dati aziendali in cui diversi utenti possono avere diverse prospettive su un determinato asset:This approach reflects the real world of enterprise data where different users can have different perspectives on a given asset:

  • Un amministratore del database può fornire informazioni sui contratti di servizio o la finestra di elaborazione disponibile per le operazioni ETL in bloccoA database administrator may provide information about service level agreements, or the available processing window for bulk ETL operations
  • Un amministratore dei dati può fornire informazioni sui processi aziendali a cui si applica l'asset o le classificazioni a cui è stato applicato dall'aziendaA data steward may provide information about the business processes to which the asset applies, or the classifications that the business has applied to it
  • Un analista finanziario può fornire informazioni sull'uso dei dati durante le attività di reporting di fine periodoA finance analyst may provide information about how the data is used during end-of-period reporting tasks

Per supportare questo esempio, ogni utente (l'amministratore del database, l'amministratore dei dati e l'analista) può aggiungere una descrizione a una singola tabella che è stata registrata nel catalogo.To support this example, each user – the DBA, the data steward, and the analyst – can add a description to a single table that has been registered in the Catalog. Tutte le descrizioni vengono gestite nel sistema e nel portale del Catalogo dati di Azure vengono visualizzate tutte le descrizioni.All descriptions are maintained in the system, and in the Azure Data Catalog portal all descriptions are displayed.

Questo modello viene applicato alla maggior parte degli elementi del modello a oggetti. I tipi di oggetto nel payload JSON, quindi, sono spesso matrici per le proprietà in cui è possibile prevedere un singleton.This pattern is applied to most of the items in the object model, so object types in the JSON payload are often arrays for properties where you might expect a singleton.

Ad esempio, sotto la radice dell'asset è disponibile una matrice di oggetti descrizione.For example, under the asset root is an array of description objects. La proprietà della matrice è denominata "descriptions".The array property is named “descriptions”. Un oggetto descrizione ha una proprietà, description.A description object has one property - description. In base al modello, ogni utente che digita una descrizione ottiene un oggetto descrizione creato per il valore fornito dall'utente.The pattern is that each user who types description gets a description object created for the value supplied by the user.

L'esperienza utente può quindi scegliere come visualizzare la combinazione.The UX can then choose how to display the combination. Esistono tre diversi modelli per la visualizzazione.There are three different patterns for display.

  • Il modello più semplice è "Mostra tutto".The simplest pattern is “Show All”. In questo modello tutti gli oggetti vengono visualizzati in una visualizzazione elenco.In this pattern, all the objects are shown in a list view. Il portale di Azure Data Catalog fa uso di questo modello per la descrizione.The Azure Data Catalog portal UX uses this pattern for description.
  • Un altro modello è "Merge".Another pattern is “Merge”. In questo modello tutti i valori dai diversi utenti vengono uniti e i duplicati vengono rimossi.In this pattern, all the values from the different users are merged together, with duplicate removed. Esempi di questo modello nell'esperienza utente nel portale del Catalogo dati di Azure sono le proprietà di tag ed esperti.Examples of this pattern in the Azure Data Catalog portal UX are the tags and experts properties.
  • Un terzo modello è "ultima scrittura prevale".A third pattern is “last writer wins”. In questo modello viene visualizzato solo il valore digitato più di recente.In this pattern, only the most recent value typed in is shown. friendlyName è un esempio di questo modello.friendlyName is an example of this pattern.

Modello a oggetti assetAsset object model

Come descritto nella sezione dei concetti chiave, il modello a oggetti del Catalogo dati di Azure include elementi che possono essere asset o annotazioni.As introduced in the Key Concepts section, the Azure Data Catalog object model includes items, which can be assets or annotations. Gli elementi dispongono di proprietà che possono essere obbligatorie o facoltative.Items have properties, which can be optional or required. Alcune proprietà si applicano a tutti gli elementi.Some properties apply to all items. Alcune proprietà si applicano a tutti gli asset.Some properties apply to all assets. Alcune proprietà si applicano solo a tipi di asset specifici.Some properties apply only to specific asset types.

Proprietà di sistemaSystem properties

Nome proprietàProperty NameTipo di datiData TypeCommentiComments
timestamptimestampDateTimeDateTimeData e ora dell'ultima modifica apportata all'elemento.The last time the item was modified. Questo campo viene generato dal server quando viene inserito un elemento e ogni volta che viene aggiornato un elemento.This field is generated by the server when an item is inserted and every time an item is updated. Il valore di questa proprietà viene ignorato durante l'input di operazioni di pubblicazione.The value of this property is ignored on input of publish operations.
ididUriUriURL assoluto dell'elemento (sola lettura).Absolute url of the item (read-only). Si tratta dell'URI indirizzabile univoco per l'elemento.It is the unique addressable URI for the item. Il valore di questa proprietà viene ignorato durante l'input di operazioni di pubblicazione.The value of this property is ignored on input of publish operations.
typetypeStringaStringTipo di asset (sola lettura).The type of the asset (read-only).
etagetagStringStringStringa che corrisponde alla versione dell'elemento che è possibile usare per il controllo della concorrenza ottimistica quando si eseguono operazioni che aggiornano gli elementi nel catalogo.A string corresponding to the version of the item that can be used for optimistic concurrency control when performing operations that update items in the catalog. È possibile usare "" per cercare corrispondenze per qualsiasi valore."" can be used to match any value.

Proprietà comuniCommon properties

Queste proprietà si applicano a tutti i tipi di asset radice e a tutti i tipi di annotazione.These properties apply to all root asset types and all annotation types.

Nome proprietàProperty NameTipo di datiData TypeCommentiComments
fromSourceSystemfromSourceSystemBooleanBooleanIndica se i dati dell'elemento sono derivati da un sistema di origine, ad esempio un database SQL Server o un database Oracle, o creati da un utente.Indicates whether item's data is derived from a source system (like Sql Server Database, Oracle Database) or authored by a user.

Proprietà radice comuniCommon root properties

Queste proprietà si applicano a tutti i tipi di asset radice.These properties apply to all root asset types.

Nome proprietàProperty NameTipo di datiData TypeCommentiComments
namenameStringStringNome derivato dalle informazioni del percorso di origine dati.A name derived from the data source location information
dsldslDataSourceLocationDataSourceLocationDescrive in modo univoco l'origine dati ed è uno degli identificatori per l'asset.Uniquely describes the data source and is one of the identifiers for the asset. Vedere la sezione relativa all'identità doppia.(See dual identity section). La struttura del percorso dell'origine dati varia in base al tipo di protocollo e di origine.The structure of the dsl varies by the protocol and source type.
dataSourcedataSourceDataSourceInfoDataSourceInfoUlteriori dettagli sul tipo di asset.More detail on the type of asset.
lastRegisteredBylastRegisteredBySecurityPrincipalSecurityPrincipalDescrive l'utente che ha registrato l'asset più di recente.Describes the user who most recently registered this asset. Contiene l'ID univoco per l'utente (upn) e un nome visualizzato (lastName e firstName).Contains both the unique id for the user (the upn) and a display name (lastName and firstName).
containerIdcontainerIdStringStringID dell'asset di contenitore per l'origine dati.Id of the container asset for the data source. Questa proprietà non è supportata per il tipo di contenitore.This property is not supported for the Container type.

Proprietà comuni di annotazione non singletonCommon non-singleton annotation properties

Queste proprietà si applicano a tutti i tipi di annotazione non singleton, ad esempio le annotazioni di cui sono consentite più occorrenze per ogni asset.These properties apply to all non-singleton annotation types (annotations, which allowed to be multiple per asset).

Nome proprietàProperty NameTipo di datiData TypeCommentiComments
keykeyStringStringChiave specificata dall'utente che identifica in modo univoco l'annotazione nella raccolta corrente.A user specified key, which uniquely identifies the annotation in the current collection. La lunghezza della chiave non può superare i 256 caratteri.The key length cannot exceed 256 characters.

Tipi di asset radiceRoot asset types

I tipi di asset radice rappresentano i diversi tipi di asset di dati che possono essere registrati nel catalogo.Root asset types are those types that represent the various types of data assets that can be registered in the catalog. Per ogni tipo radice è disponibile una vista che descrive asset e annotazioni inclusi nella vista.For each root type, there is a view, which describes asset and annotations included in the view. Il nome della vista deve essere usato nel segmento dell'URL corrispondente {vista_nome} quando un asset viene pubblicato tramite l'API REST.View name should be used in the corresponding {view_name} url segment when publishing an asset using REST API.

Tipo di asset (nome vista)Asset Type (View name)Proprietà aggiuntiveAdditional PropertiesTipo di datiData TypeAnnotazioni consentiteAllowed AnnotationsCommentiComments
Tabella ("tabelle")Table ("tables")DescrizioneDescription

FriendlyNameFriendlyName

TagTag

SchemaSchema

ColumnDescriptionColumnDescription

ColumnTagColumnTag

EspertoExpert

PreviewPreview

AccessInstructionAccessInstruction

TableDataProfileTableDataProfile

ColumnDataProfileColumnDataProfile

ColumnDataClassificationColumnDataClassification

DocumentazioneDocumentation

Tabella che rappresenta i dati tabulari.A Table represents any tabular data. Ad esempio: tabella SQL, vista SQL, tabella tabulare di Analysis Services, dimensione multidimensionale di Analysis Services, tabella Oracle e così via.For example: SQL Table, SQL View, Analysis Services Tabular Table, Analysis Services Multidimensional dimension, Oracle Table, etc.
Misura ("misure")Measure ("measures")DescrizioneDescription

FriendlyNameFriendlyName

TagTag

EspertoExpert

AccessInstructionAccessInstruction

DocumentazioneDocumentation

Tipo che rappresenta una misura di Analysis Services.This type represents an Analysis Services measure.
MisurameasureColonnaColumnMetadati che descrivono la misura.Metadata describing the measure
isCalculatedisCalculated BooleanBooleanSpecifica se la misura viene calcolata o meno.Specifies if the measure is calculated or not.
measureGroupmeasureGroupStringStringContenitore fisico per la misura.Physical container for measure
Indicatore KPI ("indicatori KPI")KPI ("kpis")DescrizioneDescription

FriendlyNameFriendlyName

TagTag

EspertoExpert

AccessInstructionAccessInstruction

DocumentazioneDocumentation

measureGroupmeasureGroupStringStringContenitore fisico per la misura.Physical container for measure
goalExpressiongoalExpressionStringStringEspressione numerica MDX o calcolo che restituisce il valore di destinazione dell'indicatore KPI.An MDX numeric expression or a calculation that returns the target value of the KPI.
valueExpressionvalueExpressionStringStringEspressione numerica MDX che restituisce il valore effettivo dell'indicatore KPI.An MDX numeric expression that returns the actual value of the KPI.
statusExpressionstatusExpressionStringStringEspressione MDX che rappresenta lo stato dell'indicatore KPI in un punto specifico nel tempo.An MDX expression that represents the state of the KPI at a specified point in time.
trendExpressiontrendExpressionStringStringEspressione MDX che restituisce il valore dell'indicatore KPI nel tempo.An MDX expression that evaluates the value of the KPI over time. La tendenza può essere un qualsiasi criterio basato sul tempo utile in un contesto aziendale specifico.The trend can be any time-based criterion that is useful in a specific business context.
Report ("report")Report ("reports")DescrizioneDescription

FriendlyNameFriendlyName

TagTag

EspertoExpert

AccessInstructionAccessInstruction

DocumentazioneDocumentation

Tipo che rappresenta un report di SQL Server Reporting Services.This type represents a SQL Server Reporting Services report
assetCreatedDateassetCreatedDateStringaString
assetCreatedByassetCreatedByStringaString
assetModifiedDateassetModifiedDateStringaString
assetModifiedByassetModifiedByStringaString
Contenitore ("contenitori")Container ("containers")DescrizioneDescription

FriendlyNameFriendlyName

TagTag

EspertoExpert

AccessInstructionAccessInstruction

DocumentazioneDocumentation

Questo tipo rappresenta un contenitore di altri asset, ad esempio un database SQL, un contenitore di BLOB di Azure o un modello di Analysis Services.This type represents a container of other assets such as a SQL database, an Azure Blobs container, or an Analysis Services model.

Tipi di annotazioneAnnotation types

I tipi di annotazione sono tipi di metadati che possono essere assegnati ad altri tipi all'interno del catalogo.Annotation types represent types of metadata that can be assigned to other types within the catalog.

Tipo di annotazione (nome della vista annidata)Annotation Type (Nested view name)Proprietà aggiuntiveAdditional PropertiesTipo di datiData TypeCommentiComments
Descrizione ("descrizioni")Description ("descriptions")Questa proprietà contiene una descrizione per un asset.This property contains a description for an asset. Ogni utente del sistema può aggiungere una descrizione.Each user of the system can add their own description. Solo tale utente può modificare l'oggetto descrizione.Only that user can edit the Description object. Gli amministratori e i proprietari di asset possono eliminare l'oggetto Description ma non modificarlo.(Admins and Asset owners can delete the Description object but not edit it). Il sistema gestisce le descrizioni degli utenti separatamente.The system maintains users' descriptions separately. Pertanto è disponibile una matrice di descrizioni in ogni asset (una per ogni utente che ha contribuito con le proprie conoscenze sull'asset, oltre a probabilmente una contenente le informazioni derivate dall'origine dati).Thus there is an array of descriptions on each asset (one for each user who has contributed their knowledge about the asset, in addition to possibly one that contains information derived from the data source).
descriptiondescriptionstringstringBreve descrizione (2-3 righe) dell'assetA short description (2-3 lines) of the asset
Tag ("tag")Tag ("tags")Questa proprietà definisce un tag per un asset.This property defines a tag for an asset. Ogni utente del sistema può aggiungere più tag per un asset.Each user of the system can add multiple tags for an asset. Solo l'utente che ha creato gli oggetti Tag può modificarli.Only the user who created Tag objects can edit them. Gli amministratori e i proprietari di asset possono eliminare l'oggetto Tag ma non modificarlo.(Admins and Asset owners can delete the Tag object but not edit it). Il sistema gestisce i tag degli utenti separatamente.The system maintains users' tags separately. Di conseguenza, è disponibile una matrice di oggetti Tag in ogni asset.Thus there is an array of Tag objects on each asset.
tagtagstringstringTag che descrive l'asset.A tag describing the asset.
FriendlyName ("friendlyName")FriendlyName ("friendlyName")Questa proprietà contiene un nome descrittivo per un asset.This property contains a friendly name for an asset. FriendlyName è un'annotazione singleton. È possibile aggiungere una sola annotazione FriendlyName a un asset.FriendlyName is a singleton annotation - only one FriendlyName can be added to an asset. Solo l'utente che ha creato l'oggetto FriendlyName può modificarlo.Only the user who created FriendlyName object can edit it. Gli amministratori e i proprietari di asset possono eliminare l'oggetto FriendlyName ma non modificarlo.(Admins and Asset owners can delete the FriendlyName object but not edit it). Il sistema gestisce i nomi descrittivi degli utenti separatamente.The system maintains users' friendly names separately.
friendlyNamefriendlyNamestringstringNome descrittivo dell'asset.A friendly name of the asset.
Schema ("schema")Schema ("schema")Schema che descrive la struttura dei dati.The Schema describes the structure of the data. Elenca i nomi di attributo, come colonna, attributo, campo e così via, i tipi e altri metadati.It lists the attribute (column, attribute, field, etc.) names, types as well other metadata. Queste informazioni sono derivate dall'origine dati.This information is all derived from the data source. Lo schema è un'annotazione singleton. È possibile aggiungere un solo schema a un asset.Schema is a singleton annotation - only one Schema can be added for an asset.
columnscolumnsColumn[]Column[]Matrice di oggetti colonna.An array of column objects. Descrivono la colonna con le informazioni derivate dall'origine dati.They describe the column with information derived from the data source.
ColumnDescription ("columnDescriptions")ColumnDescription ("columnDescriptions")Questa proprietà contiene una descrizione per una colonna.This property contains a description for a column. Tutti gli utenti del sistema possono aggiungere descrizioni per più colonne, con un massimo di una descrizione per ogni colonna.Each user of the system can add their own descriptions for multiple columns (at most one per column). Solo l'utente che ha creato gli oggetti ColumnDescription può modificarli.Only the user who created ColumnDescription objects can edit them. Gli amministratori e i proprietari di asset possono eliminare l'oggetto ColumnDescription ma non modificarlo.(Admins and Asset owners can delete the ColumnDescription object but not edit it). Il sistema gestisce le descrizioni delle colonne dell'utente separatamente.The system maintains these user's column descriptions separately. Di conseguenza, è disponibile una matrice di oggetti ColumnDescription in ogni asset (una per colonna per ogni utente che ha contribuito con le proprie conoscenze sulla colonna). Inoltre, è possibile che ce ne sia un'altra che contiene le informazioni derivate dall'origine dati.Thus there is an array of ColumnDescription objects on each asset (one per column for each user who has contributed their knowledge about the column in addition to possibly one that contains information derived from the data source). ColumnDescription è associato in modo generico allo schema, quindi può non essere sincronizzato. ColumnDescription potrebbe descrivere una colonna non più presente nello schema.The ColumnDescription is loosely bound to the Schema so it can get out of sync. The ColumnDescription might describe a column that no longer exists in the schema. La sincronizzazione tra descrizione e schema spetta al writer. Le informazioni sulla descrizione delle colonne eventualmente presenti nell'origine dati sono oggetti ColumnDescription aggiuntivi che vengono creati durante l'esecuzione dello strumento.It is up to the writer to keep description and schema in sync. The data source may also have columns description information and they are additional ColumnDescription objects that would be created when running the tool.
columnNamecolumnNameStringaStringNome della colonna a cui fa riferimento questa descrizione.The name of the column this description refers to.
descriptiondescriptionStringaStringBreve descrizione (2-3 righe) della colonna.a short description (2-3 lines) of the column.
ColumnTag ("columnTags")ColumnTag ("columnTags")Questa proprietà contiene un tag per una colonna.This property contains a tag for a column. Ogni utente del sistema può aggiungere più tag a una determinata colonna e può aggiungere tag a più colonne.Each user of the system can add multiple tags for a given column and can add tags for multiple columns. Solo l'utente che ha creato gli oggetti ColumnTag può modificarli.Only the user who created ColumnTag objects can edit them. Gli amministratori e i proprietari di asset possono eliminare l'oggetto ColumnTag ma non modificarlo.(Admins and Asset owners can delete the ColumnTag object but not edit it). Il sistema gestisce i tag delle colonne dell'utente separatamente.The system maintains these users' column tags separately. Di conseguenza, è disponibile una matrice di oggetti ColumnTag in ogni asset.Thus there is an array of ColumnTag objects on each asset. ColumnTag è associato in modo generico allo schema, quindi può non essere sincronizzato. ColumnTag potrebbe descrivere una colonna non più presente nello schema.The ColumnTag is loosely bound to the schema so it can get out of sync. The ColumnTag might describe a column that no longer exists in the schema. La sincronizzazione tra tag delle colonne e schema spetta al writer.It is up to the writer to keep column tag and schema in sync.
columnNamecolumnNameStringaStringNome della colonna a cui fa riferimento questo tag.The name of the column this tag refers to.
tagtagStringaStringTag che descrive la colonna.A tag describing the column.
Esperto ("esperti")Expert ("experts")Questa proprietà contiene un utente che viene considerato un esperto nel set di dati.This property contains a user who is considered an expert in the data set. Le opinioni degli esperti, ad esempio le descrizioni, vengono visualizzate all'inizio dell'esperienza utente nell'elenco delle descrizioni.The experts’ opinions(descriptions) bubble to the top of the UX when listing descriptions. Ogni utente può specificare i propri esperti.Each user can specify their own experts. Solo tale utente può modificare l'oggetto esperti.Only that user can edit the experts object. Gli amministratori e i proprietari di asset possono eliminare l'oggetto Expert ma non modificarlo.(Admins and Asset owners can delete the Expert objects but not edit it).
espertoexpertSecurityPrincipalSecurityPrincipal
Anteprima ("anteprime")Preview ("previews")L'anteprima contiene uno snapshot delle prime 20 righe di dati per l'asset.The preview contains a snapshot of the top 20 rows of data for the asset. L'anteprima risulta utile solo per alcuni tipi di asset, ad esempio per la tabella ma non per la misura.Preview only make sense for some types of assets (it makes sense for Table but not for Measure).
previewpreviewobject[]object[]Matrice di oggetti che rappresentano una colonna.Array of objects that represent a column. Ogni oggetto ha un mapping di proprietà a una colonna con un valore della colonna per la riga.Each object has a property mapping to a column with a value for that column for the row.
AccessInstruction ("accessInstructions")AccessInstruction ("accessInstructions")
mimeTypemimeTypestringstringIl tipo mime del contenuto.The mime type of the content.
contentcontentstringstringIstruzioni su come ottenere l'accesso a questa risorsa di dati.The instructions for how to get access to this data asset. Il contenuto può essere un URL, un indirizzo di posta elettronica o un set di istruzioni.The content could be a URL, an email address, or a set of instructions.
TableDataProfile ("tableDataProfiles")TableDataProfile ("tableDataProfiles")
numberOfRowsnumberOfRowsintintIl numero di righe nel set di datiThe number of rows in the data set
sizesizelonglongLa dimensione in byte del set di dati.The size in bytes of the data set.
schemaModifiedTimeschemaModifiedTimestringstringL'ora dell'ultima modifica apportata allo schemaThe last time the schema was modified
dataModifiedTimedataModifiedTimestringastringOra dell'ultima modifica al set di dati, con aggiunta, modifica o eliminazione di datiThe last time the data set was modified (data was added, modified, or delete)
ColumnsDataProfile ("columnsDataProfiles")ColumnsDataProfile ("columnsDataProfiles")
columnscolumnsColumnDataProfile[]ColumnDataProfile[]Matrice di profili dati della colonna.An array of column data profiles.
ColumnDataClassification ("columnDataClassifications")ColumnDataClassification ("columnDataClassifications")
columnNamecolumnNameStringStringNome della colonna a cui fa riferimento questa classificazione.The name of the column this classification refers to.
classificazioneclassificationStringStringLa classificazione dei dati in questa colonna.The classification of the data in this column.
Documentazione ("documentazione")Documentation ("documentation")Un determinato asset può avere solo una documentazione associata.A given asset can have only one documentation associated with it.
mimeTypemimeTypestringstringIl tipo mime del contenuto.The mime type of the content.
contentcontentstringstringIl contenuto della documentazione.The documentation content.

Tipi comuniCommon types

I tipi comuni possono essere usati come tipi per proprietà, ma non sono elementi.Common types can be used as the types for properties, but are not Items.

Tipo comuneCommon TypeProprietàPropertiesTipo di datiData TypeCommentiComments
DataSourceInfoDataSourceInfo
sourceTypesourceTypestringstringDescrive il tipo di origine dati.Describes the type of data source. Ad esempio: SQL Server, database Oracle e così via.For example: SQL Server, Oracle Database, etc.
objectTypeobjectTypestringastringDescrive il tipo di oggetto nell'origine dati.Describes the type of object in the data source. Ad esempio: tabella, vista per SQL Server.For example: Table, View for SQL Server.
DataSourceLocationDataSourceLocation
protocolprotocolstringstringObbligatorio.Required. Descrive un protocollo usato per comunicare con l'origine dati.Describes a protocol used to communicate with the data source. Ad esempio: "tds" per SQL Server, "oracle" per Oracle e così via. Per l'elenco dei protocolli attualmente supportati, vedere la Specifica di riferimento per l'origine dati: struttura DSL.For example: "tds" for SQl Server, "oracle" for Oracle, etc. Refer to Data source reference specification - DSL Structure for the list of currently supported protocols.
AddressaddressDizionario<string, object>Dictionary<string, object>Obbligatorio.Required. Si tratta di un set di dati specifico per il protocollo usato per identificare l'origine dati a cui si fa riferimento.Address is a set of data specific to the protocol that is used to identify the data source being referenced. Dati indirizzo specifici per un determinato protocollo, vale a dire privi di significato se il protocollo non è noto.The address data scoped to a particular protocol, meaning it is meaningless without knowing the protocol.
authenticationauthenticationstringastringFacoltativo.Optional. Schema di autenticazione usato per comunicare con l'origine dati.The authentication scheme used to communicate with the data source. Ad esempio, Windows, OAuth e così via.For example: windows, oauth, etc.
connectionPropertiesconnectionPropertiesDizionario<string, object>Dictionary<string, object>Facoltativo.Optional. Altre informazioni su come connettersi a un'origine dati.Additional information on how to connect to a data source.
SecurityPrincipalSecurityPrincipalIl back-end non esegue alcuna convalida delle proprietà fornite in base ad AAD durante la pubblicazione.The backend does not perform any validation of provided properties against AAD during publishing.
upnupnstringstringIndirizzo e-mail univoco dell'utente.Unique email address of user. Deve essere specificato se objectId non viene fornito o se è nel contesto della proprietà "lastRegisteredBy". In caso contrario, è facoltativo.Must be specified if objectId is not provided or in the context of "lastRegisteredBy" property, otherwise optional.
objectIdobjectIdGuidGuidIdentità AAD del gruppo di utenti o di sicurezza.User or security group AAD identity. Facoltativo.Optional. Deve essere specificato se upn non viene fornito. In caso contrario, è facoltativo.Must be specified if upn is not provided, otherwise optional.
firstNamefirstNamestringstringNome dell'utente (per scopi di visualizzazione).First name of user (for display purposes). Facoltativo.Optional. Valido solo nel contesto della proprietà "lastRegisteredBy".Only valid in the context of "lastRegisteredBy" property. Non può essere specificato quando si fornisce l'entità di sicurezza per "ruoli", "autorizzazioni" ed "esperti".Cannot be specified when providing security principal for "roles", "permissions" and "experts".
lastNamelastNamestringstringCognome dell'utente (per scopi di visualizzazione).Last name of user (for display purposes). Facoltativo.Optional. Valido solo nel contesto della proprietà "lastRegisteredBy".Only valid in the context of "lastRegisteredBy" property. Non può essere specificato quando si fornisce l'entità di sicurezza per "ruoli", "autorizzazioni" ed "esperti".Cannot be specified when providing security principal for "roles", "permissions" and "experts".
ColonnaColumn
namenamestringstringNome della colonna o dell'attributo.Name of the column or attribute.
typetypestringstringTipo di dati della colonna o dell'attributo.data type of the column or attribute. I tipi consentiti dipendono dal sourceType dei dati dell'asset.The Allowable types depend on data sourceType of the asset. È supportato un solo subset di tipi.Only a subset of types is supported.
maxLengthmaxLengthintintLunghezza massima consentita per la colonna o l'attributo.The maximum length allowed for the column or attribute. Derivata dall'origine dati.Derived from data source. Valida solo per alcuni tipi di origine.Only applicable to some source types.
precisionprecisionbytebytePrecisione della colonna o dell'attributo.The precision for the column or attribute. Derivata dall'origine dati.Derived from data source. Valida solo per alcuni tipi di origine.Only applicable to some source types.
isNullableisNullableBooleanBooleanVerifica se la colonna può avere un valore null o meno.Whether the column is allowed to have a null value or not. Derivata dall'origine dati.Derived from data source. Valida solo per alcuni tipi di origine.Only applicable to some source types.
expressionexpressionstringastringSe il valore è una colonna calcolata, questo campo contiene l'espressione che esprime il valore.If the value is a calculated column, this field contains the expression that expresses the value. Derivata dall'origine dati.Derived from data source. Valida solo per alcuni tipi di origine.Only applicable to some source types.
ColumnDataProfileColumnDataProfile
columnNamecolumnName stringstringIl nome della colonnaThe name of the column
typetype stringstringIl tipo della colonnaThe type of the column
minmin stringstringIl valore minimo nel set di datiThe minimum value in the data set
maxmax stringstringIl valore massimo nel set di datiThe maximum value in the data set
avgavg doubledoubleIl valore medio del set di datiThe average value in the data set
stdevstdev doubledoubleLa deviazione standard per il set di datiThe standard deviation for the data set
nullCountnullCount intintIl numero di valori null nel set di datiThe count of null values in the data set
distinctCountdistinctCount intintIl numero di valori distinct nel set di datiThe count of distinct values in the data set

Identità di assetAsset identity

Azure Data Catalog usa le proprietà Identity e "protocol" disponibili nel contenitore della proprietà "address", nella proprietà DataSourceLocation "dsl", per generare l'identità dell'asset usata per trovare l'asset nel catalogo.Azure Data Catalog uses "protocol" and identity properties from the "address" property bag of the DataSourceLocation "dsl" property to generate identity of the asset, which is used to address the asset inside the Catalog. Ad esempio, le proprietà Identity del protocollo "tds" sono "server", "database", "schema" e "object".For example, the "tds" protocol has identity properties "server", "database", "schema" and "object". Per generare l'identità dell'asset tabella di SQL Server vengono usate combinazioni delle proprietà Identity e "protocol".The combinations of the protocol and the identity properties are used to generate the identity of the SQL Server Table Asset. Azure Data Catalog offre vari protocolli di origine dati predefiniti, che sono elencati nella specifica di riferimento per l'origine dati: struttura DSL.Azure Data Catalog provides several built-in data source protocols, which are listed at Data source reference specification - DSL Structure. Il set di protocolli supportati può essere esteso a livello di codice. Vedere in proposito il riferimento all'API REST di Data Catalog.The set of supported protocols can be extended programmatically (Refer to Data Catalog REST API reference). Gli amministratori di Data Catalog possono registrare protocolli di origine dati personalizzati.Administrators of the Catalog can register custom data source protocols. La tabella seguente illustra le proprietà necessarie per registrare un protocollo personalizzato.The following table describes the properties needed to register a custom protocol.

Specifica del protocollo di origine dati personalizzatoCustom data source protocol specification

TipoTypeProprietàPropertiesTipo di datiData TypeCommentiComments
DataSourceProtocolDataSourceProtocol
namespacenamespacestringstringSpazio dei nomi del protocollo.The namespace of the protocol. Lo spazio dei nomi deve avere una lunghezza compresa tra 1 e 255 caratteri e contenere una o più parti non vuote separate da un punto (.).Namespace must be from 1 to 255 characters long, contain one or more non-empty parts separated by dot (.). Ogni parte deve avere una lunghezza compresa tra 1 e 255 caratteri, iniziare con una lettera e contenere solo lettere e numeri.Each part must be from 1 to 255 characters long, start with a letter and contain only letters and numbers.
namenamestringstringNome del protocollo.The name of the protocol. Lo spazio dei nomi deve avere una lunghezza compresa tra 1 e 255 caratteri, iniziare con una lettera e contenere solo lettere, numeri e trattini (-).Name must be from 1 to 255 characters long, start with a letter and contain only letters, numbers, and the dash (-) character.
identityPropertiesidentityPropertiesDataSourceProtocolIdentityProperty[]DataSourceProtocolIdentityProperty[]Elenco di proprietà Identity, deve contenere almeno una proprietà, ma non oltre 20.List of identity properties, must contain at least one, but no more than 20 properties. Ad esempio: "server", "database", "schema", "object" sono proprietà Identity del protocollo "tds".For example: "server", "database", "schema", "object" are identity properties of the "tds" protocol.
identitySetsidentitySetsDataSourceProtocolIdentitySet[]DataSourceProtocolIdentitySet[]Elenco di set di identità.List of identity sets. Definisce i set di proprietà Identity che rappresentano l'identità valida dell'asset.Defines sets of identity properties, which represent valid asset's identity. Deve contenere almeno un set, ma non oltre 20.Must contain at least one, but no more than 20 sets. Ad esempio: {"server", "database", "schema" e "object"} è un set di identità del protocollo "tds", che definisce l'identità dell'asset Tabella di SQL Server.For example: {"server", "database", "schema" and "object"} is an identity set for "tds" protocol, which defines identity of Sql Server Table asset.
DataSourceProtocolIdentityPropertyDataSourceProtocolIdentityProperty
namenamestringstringNome della proprietà.The name of the property. Il nome della proprietà deve avere una lunghezza compresa tra 1 e 100 caratteri, iniziare con una lettera e può contenere solo lettere e numeri.Name must be from 1 to 100 characters long, start with a letter and can contain only letters and numbers.
typetypestringstringTipo della proprietà.The type of the property. Valori supportati: "bool", boolean", "byte", "guid", "int", "integer", "long", "string", "url"Supported values: "bool", boolean", "byte", "guid", "int", "integer", "long", "string", "url"
ignoreCaseignoreCaseboolboolIndica se deve essere ignorato il caso quando si usa il valore della proprietà.Indicates whether case should be ignored when using property's value. Può essere specificato solo per le proprietà di tipo "string".Can only be specified for properties with "string" type. Il valore predefinito è False.Default value is false.
urlPathSegmentsIgnoreCaseurlPathSegmentsIgnoreCasebool[]bool[]Indica se deve essere ignorato il caso per ogni segmento del percorso URL.Indicates whether case should be ignored for each segment of the url's path. Può essere specificato solo per le proprietà di tipo "url".Can only be specified for properties with "url" type. Il valore predefinito è [false].Default value is [false].
DataSourceProtocolIdentitySetDataSourceProtocolIdentitySet
namenamestringastringNome del set di identità.The name of the identity set.
propertiespropertiesstring[]string[]Elenco delle proprietà Identity incluse in questo set.The list of identity properties included into this identity set. Non può contenere duplicati.It cannot contain duplicates. Ogni proprietà a cui fa riferimento il set di identità deve essere definita nell'elenco di "identityProperties" del protocollo.Each property referenced by identity set must be defined in the list of "identityProperties" of the protocol.

Ruoli e autorizzazioneRoles and authorization

Catalogo dati di Microsoft Azure offre funzionalità di autorizzazione per le operazioni CRUD su asset e annotazioni.Microsoft Azure Data Catalog provides authorization capabilities for CRUD operations on assets and annotations.

Concetti chiaveKey concepts

Catalogo dati di Azure usa due meccanismi di autorizzazione:The Azure Data Catalog uses two authorization mechanisms:

  • Autorizzazione basata sui ruoliRole-based authorization
  • Autorizzazione basata sulle autorizzazioniPermission-based authorization

RuoliRoles

Sono disponibili tre ruoli: Amministratore, Proprietario e Collaboratore.There are three roles: Administrator, Owner, and Contributor. Ogni ruolo ha un ambito e dei diritti che sono riepilogati nella tabella seguente.Each role has its scope and rights, which are summarized in the following table.

RuoloRoleAmbitoScopeDirittiRights
AmministratoreAdministratorCatalogo (ad esempio tutti gli asset o le annotazioni del catalogo)Catalog (all assets/annotations in the Catalog)Read Delete ViewRolesRead Delete ViewRoles ChangeOwnership ChangeVisibility ViewPermissionsChangeOwnership ChangeVisibility ViewPermissions
ProprietarioOwnerOgni asset (elemento radice)Each asset (root item)Read Delete ViewRolesRead Delete ViewRoles ChangeOwnership ChangeVisibility ViewPermissionsChangeOwnership ChangeVisibility ViewPermissions
CollaboratoreContributorOgni singolo asset e annotazioneEach individual asset and annotationRead Update Delete ViewRoles Nota: tutti i diritti vengono revocati se il diritto Read sull'elemento viene revocato dall'autoreRead Update Delete ViewRoles Note: all the rights are revoked if the Read right on the item is revoked from the Contributor

Nota

I diritti Read, Update, Delete e ViewRoles sono applicabili a qualsiasi elemento (asset o annotazione) mentre TakeOwnership, ChangeOwnership, ChangeVisibility e ViewPermissions sono applicabili solo all'asset radice.Read, Update, Delete, ViewRoles rights are applicable to any item (asset or annotation) while TakeOwnership, ChangeOwnership, ChangeVisibility, ViewPermissions are only applicable to the root asset.

Delete si applica a un elemento e agli eventuali elementi secondari o al singolo elemento sottostante.Delete right applies to an item and any subitems or single item underneath it. Ad esempio, l'eliminazione di un asset comporta l'eliminazione delle annotazioni dell'asset.For example, deleting an asset also deletes any annotations for that asset.

AutorizzazioniPermissions

L'autorizzazione è come un elenco di voci di controllo di accesso.Permission is as list of access control entries. Ogni voce di controllo di accesso assegna un set di diritti a un'entità di sicurezza.Each access control entry assigns set of rights to a security principal. Le autorizzazioni possono essere specificate solo su un asset, vale a dire un elemento radice, e si applicano all'asset e ai relativi elementi secondari.Permissions can only be specified on an asset (that is, root item) and apply to the asset and any subitems.

Durante l'anteprima di Azure Data Catalog solo il diritto Read è supportato nell'elenco delle autorizzazioni per consentire allo scenario di limitare la visibilità a un asset.During the Azure Data Catalog preview, only Read right is supported in the permissions list to enable scenario to restrict visibility of an asset.

Per impostazione predefinita tutti gli utenti autenticati hanno il diritto Read per qualsiasi elemento del catalogo, a meno che la visibilità non sia limitata al set di entità nelle autorizzazioni.By default any authenticated user has Read right for any item in the catalog unless visibility is restricted to the set of principals in the permissions.

API RESTREST API

Le richieste dell'elemento di visualizzazione PUT e POST possono essere usate per controllare i ruoli e le autorizzazioni: oltre al payload dell'elemento, è possibile specificare due proprietà di sistema, ruoli e autorizzazioni.PUT and POST view item requests can be used to control roles and permissions: in addition to item payload, two system properties can be specified roles and permissions.

Nota

permissions si applicano solo a un elemento radice.permissions only applicable to a root item.

Proprietario si applica solo a un elemento radice.Owner role only applicable to a root item.

Per impostazione predefinita quando viene creato un elemento nel catalogo, il relativo Collaboratore è impostato sull'utente attualmente autenticato.By default when an item is created in the catalog its Contributor is set to the currently authenticated user. Se l'elemento deve poter essere aggiornato da tutti, è necessario che Collaboratore sia impostato sull'entità di sicurezza speciale <Tutti> nella proprietà ruoli quando l'elemento viene pubblicato per la prima volta. Vedere l'esempio riportato di seguito.If item should be updatable by everyone, Contributor should be set to <Everyone> special security principal in the roles property when item is first published (refer to the following example). Collaboratore non può essere modificato e rimane invariato per la durata di un elemento. Neanche Amministratore o Proprietario hanno il diritto di modificare il ruolo Collaboratore.Contributor cannot be changed and stays the same during life-time of an item (even Administrator or Owner doesn’t have the right to change the Contributor). L'unico valore supportato per l'impostazione esplicita di Collaboratore è <Tutti>: ad esempio, Collaboratore può essere solo un utente che ha creato un elemento o <Tutti>.The only value supported for the explicit setting of the Contributor is <Everyone>: Contributor can only be a user who created an item or <Everyone>.

esempiExamples

Impostare collaboratore su <Tutti> durante la pubblicazione di un elemento.Set Contributor to <Everyone> when publishing an item. L'entità di sicurezza speciale <Tutti> ha come objectId "00000000-0000-0000-0000-000000000201".Special security principal <Everyone> has objectId "00000000-0000-0000-0000-000000000201". POST: https://api.azuredatacatalog.com/catalogs/default/views/tables/?api-version=2016-03-30POST https://api.azuredatacatalog.com/catalogs/default/views/tables/?api-version=2016-03-30

Nota

Alcune implementazioni di client HTTP possono ripetere automaticamente l'invio di richieste in caso di risposta 302 dal server, eliminando in genere le intestazioni di autorizzazione dalla richiesta.Some HTTP client implementations may automatically reissue requests in response to a 302 from the server, but typically strip Authorization headers from the request. Dato che l'intestazione dell'autorizzazione è obbligatoria per l'invio di richieste ad Azure Data Catalog, è necessario assicurarsi che sia ancora disponibile quando si invia di nuovo una richiesta a un percorso di reindirizzamento specificato da Azure Data Catalog.Since the Authorization header is required to make requests to Azure Data Catalog, you must ensure the Authorization header is still provided when reissuing a request to a redirect location specified by Azure Data Catalog. L'esempio di codice seguente offre una dimostrazione usando l'oggetto .NET HttpWebRequest.The following sample code demonstrates it using the .NET HttpWebRequest object.

CorpoBody

{
    "roles": [
        {
            "role": "Contributor",
            "members": [
                {
                    "objectId": "00000000-0000-0000-0000-000000000201"
                }
            ]
        }
    ]
}

Assegnare i proprietari e limitare la visibilità di un elemento radice esistente: PUT https://api.azuredatacatalog.com/catalogs/default/views/tables/042297b0...1be45ecd462a?api-version=2016-03-30Assign owners and restrict visibility for an existing root item: PUT https://api.azuredatacatalog.com/catalogs/default/views/tables/042297b0...1be45ecd462a?api-version=2016-03-30

{
    "roles": [
        {
            "role": "Owner",
            "members": [
                {
                    "objectId": "c4159539-846a-45af-bdfb-58efd3772b43",
                    "upn": "user1@contoso.com"
                },
                {
                    "objectId": "fdabd95b-7c56-47d6-a6ba-a7c5f264533f",
                    "upn": "user2@contoso.com"
                }
            ]
        }
    ],
    "permissions": [
        {
            "principal": {
                "objectId": "27b9a0eb-bb71-4297-9f1f-c462dab7192a",
                "upn": "user3@contoso.com"
            },
            "rights": [
                {
                    "right": "Read"
                }
            ]
        },
        {
            "principal": {
                "objectId": "4c8bc8ce-225c-4fcf-b09a-047030baab31",
                "upn": "user4@contoso.com"
            },
            "rights": [
                {
                    "right": "Read"
                }
            ]
        }
    ]
}

Nota

In PUT non è necessario specificare un payload dell'elemento nel corpo: PUT consente di aggiornare solo i ruoli e/o le autorizzazioni.In PUT it’s not required to specify an item payload in the body: PUT can be used to update just roles and/or permissions.