Copiare dati da Cassandra usando Azure Data FactoryCopy data from Cassandra using Azure Data Factory

Questo articolo illustra come usare l'attività di copia in Azure Data Factory per copiare dati da un database Cassandra.This article outlines how to use the Copy Activity in Azure Data Factory to copy data from a Cassandra database. Si basa sull'articolo di panoramica dell'attività di copia che presenta una panoramica generale sull'attività di copia.It builds on the copy activity overview article that presents a general overview of copy activity.

Funzionalità supportateSupported capabilities

Questo connettore Cassandra è supportato per le attività seguenti:This Cassandra connector is supported for the following activities:

È possibile copiare dati da un database Cassandra in qualsiasi archivio dati di sink supportato.You can copy data from Cassandra database to any supported sink data store. Per un elenco degli archivi dati supportati come origini/sink dall'attività di copia, vedere la tabella relativa agli archivi dati supportati.For a list of data stores that are supported as sources/sinks by the copy activity, see the Supported data stores table.

In particolare, il connettore Cassandra supporta:Specifically, this Cassandra connector supports:

  • Cassandra versioni 2.x e 3.x.Cassandra versions 2.x and 3.x.
  • La copia dei dati usando l'autenticazione Di base o Anonima.Copying data using Basic or Anonymous authentication.

Nota

Per attività in esecuzione nel runtime di integrazione self-hosted, Cassandra 3.x è supportato dalla versione 3.7 del runtime di integrazione e versioni successive.For activity running on Self-hosted Integration Runtime, Cassandra 3.x is supported since IR version 3.7 and above.

PrerequisitiPrerequisites

Se l'archivio dati è configurato in uno dei modi seguenti, è necessario configurare un Integration Runtime self-hosted per connettersi a questo archivio dati:If your data store is configured in one of the following ways, you need to set up a Self-hosted Integration Runtime in order to connect to this data store:

  • L'archivio dati si trova all'interno di una rete locale, all'interno di una rete virtuale di Azure o all'interno di un cloud privato virtuale di Amazon.The data store is located inside an on-premises network, inside Azure Virtual Network, or inside Amazon Virtual Private Cloud.
  • L'archivio dati è un servizio dati cloud gestito in cui l'accesso è limitato agli indirizzi IP consentiti nelle regole del firewall.The data store is a managed cloud data service where the access is restricted to IPs whitelisted in the firewall rules.

Il runtime di integrazione offre un driver per Cassandra integrato e non è quindi necessario installare manualmente alcun driver quando si copiano dati da/in Cassandra.The Integration Runtime provides a built-in Cassandra driver, therefore you don't need to manually install any driver when copying data from/to Cassandra.

Inizia oraGetting started

È possibile usare l'attività di copia con una pipeline tramite uno degli strumenti o degli SDK seguenti.You can use one of the following tools or SDKs to use the copy activity with a pipeline. Per istruzioni dettagliate, selezionare un collegamento:Select a link for step-by-step instructions:

Le sezioni seguenti riportano informazioni dettagliate sulle proprietà che vengono usate per definire entità di Data Factory specifiche per il connettore Cassandra.The following sections provide details about properties that are used to define Data Factory entities specific to Cassandra connector.

Proprietà del servizio collegatoLinked service properties

Per il servizio collegato di Cassandra sono supportate le proprietà seguenti:The following properties are supported for Cassandra linked service:

ProprietàProperty DescriptionDescription ObbligatorioRequired
typetype La proprietà type deve essere impostata su: CassandraThe type property must be set to: Cassandra Yes
hosthost Uno o più indirizzi IP o nomi host di server Cassandra.One or more IP addresses or host names of Cassandra servers.
Specificare un elenco delimitato da virgole degli indirizzi IP o nomi host per la connessione a tutti i server contemporaneamente.Specify a comma-separated list of IP addresses or host names to connect to all servers concurrently.
Yes
portport La porta TCP che il server Cassandra usa per ascoltare le connessioni client.The TCP port that the Cassandra server uses to listen for client connections. No (il valore predefinito è 9042)No (default is 9042)
authenticationTypeauthenticationType Tipo di autenticazione usato per la connessione al database Cassandra.Type of authentication used to connect to the Cassandra database.
I valori consentiti sono: Di base e Anonima.Allowed values are: Basic, and Anonymous.
Yes
usernameusername Specificare il nome utente per l'account utente.Specify user name for the user account. Sì, se authenticationType è impostato su Basic.Yes, if authenticationType is set to Basic.
passwordpassword Specifica la password per l'account utente.Specify password for the user account. Contrassegnare questo campo come SecureString per archiviarlo in modo sicuro in Azure Data Factory oppure fare riferimento a un segreto archiviato in Azure Key Vault.Mark this field as a SecureString to store it securely in Data Factory, or reference a secret stored in Azure Key Vault. Sì, se authenticationType è impostato su Basic.Yes, if authenticationType is set to Basic.
connectViaconnectVia Il runtime di integrazione da usare per la connessione all'archivio dati.The Integration Runtime to be used to connect to the data store. Ulteriori informazioni sono disponibili nella sezione prerequisiti .Learn more from Prerequisites section. Se non specificato, viene usato il runtime di integrazione di Azure predefinito.If not specified, it uses the default Azure Integration Runtime. NoNo

Nota

La connessione a Cassandra mediante SSL non è attualmente supportata.Currently connection to Cassandra using SSL is not supported.

Esempio:Example:

{
    "name": "CassandraLinkedService",
    "properties": {
        "type": "Cassandra",
        "typeProperties": {
            "host": "<host>",
            "authenticationType": "Basic",
            "username": "<username>",
            "password": {
                "type": "SecureString",
                "value": "<password>"
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Proprietà del set di datiDataset properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione di set di dati, vedere l'articolo sui set di dati.For a full list of sections and properties available for defining datasets, see the datasets article. Questa sezione presenta un elenco delle proprietà supportate dal set di dati Cassandra.This section provides a list of properties supported by Cassandra dataset.

Per copiare dati da Cassandra, impostare la proprietà type del set di dati su CassandraTable.To copy data from Cassandra, set the type property of the dataset to CassandraTable. Sono supportate le proprietà seguenti:The following properties are supported:

ProprietàProperty DescriptionDescription ObbligatorioRequired
typetype La proprietà type del set di dati deve essere impostata su: CassandraTableThe type property of the dataset must be set to: CassandraTable Yes
keyspacekeyspace Nome del keyspace o schema nel database Cassandra.Name of the keyspace or schema in Cassandra database. No (se per "CassandraSource" è specificato "query")No (if "query" for "CassandraSource" is specified)
tableNametableName Nome della tabella in un database Cassandra.Name of the table in Cassandra database. No (se per "CassandraSource" è specificato "query")No (if "query" for "CassandraSource" is specified)

Esempio:Example:

{
    "name": "CassandraDataset",
    "properties": {
        "type": "CassandraTable",
        "typeProperties": {
            "keySpace": "<keyspace name>",
            "tableName": "<table name>"
        },
        "schema": [],
        "linkedServiceName": {
            "referenceName": "<Cassandra linked service name>",
            "type": "LinkedServiceReference"
        }
    }
}

Proprietà dell'attività di copiaCopy activity properties

Per un elenco completo delle sezioni e delle proprietà disponibili per la definizione delle attività, vedere l'articolo sulle pipeline.For a full list of sections and properties available for defining activities, see the Pipelines article. Questa sezione presenta un elenco delle proprietà supportate dall'origine Cassandra.This section provides a list of properties supported by Cassandra source.

Cassandra come origineCassandra as source

Per copiare dati da Cassandra, impostare il tipo di origine nell'attività di copia su CassandraSource.To copy data from Cassandra, set the source type in the copy activity to CassandraSource. Nella sezione origine dell'attività di copia sono supportate le proprietà seguenti:The following properties are supported in the copy activity source section:

ProprietàProperty DescriptionDescription ObbligatorioRequired
typetype La proprietà type dell'origine dell'attività di copia deve essere impostata su: CassandraSourceThe type property of the copy activity source must be set to: CassandraSource Yes
queryquery Usare la query personalizzata per leggere i dati.Use the custom query to read data. Query SQL-92 o query CQL.SQL-92 query or CQL query. Vedere il riferimento a CQL.See CQL reference.

Quando si usa una query SQL, specificare nome keyspace.nome tabella per indicare la tabella su cui eseguire la query.When using SQL query, specify keyspace name.table name to represent the table you want to query.
No (se nel set di dati sono specificati "tableName" e "keyspace").No (if "tableName" and "keyspace" in dataset are specified).
consistencyLevelconsistencyLevel Il livello di coerenza specifica quante repliche devono rispondere a una richiesta di lettura prima della restituzione dei dati all'applicazione client.The consistency level specifies how many replicas must respond to a read request before returning data to the client application. Cassandra controlla il numero di repliche specificato perché i dati soddisfino la richiesta di lettura.Cassandra checks the specified number of replicas for data to satisfy the read request. Per informazioni dettagliate, vedere Configuring data consistency (Configurazione della coerenza dei dati).See Configuring data consistency for details.

I valori consentiti sono: ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM e LOCAL_ONE.Allowed values are: ONE, TWO, THREE, QUORUM, ALL, LOCAL_QUORUM, EACH_QUORUM, and LOCAL_ONE.
No (il valore predefinito è ONE)No (default is ONE)

Esempio:Example:

"activities":[
    {
        "name": "CopyFromCassandra",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cassandra input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CassandraSource",
                "query": "select id, firstname, lastname from mykeyspace.mytable"
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Mapping dei tipi di dati per CassandraData type mapping for Cassandra

Quando si copiano dati da Cassandra, vengono usati i mapping seguenti tra i tipi di dati di Cassandra e i tipi di dati provvisori di Azure Data Factory.When copying data from Cassandra, the following mappings are used from Cassandra data types to Azure Data Factory interim data types. Vedere Mapping dello schema e del tipo di dati per informazioni su come l'attività di copia esegue il mapping dello schema di origine e del tipo di dati al sink.See Schema and data type mappings to learn about how copy activity maps the source schema and data type to the sink.

Tipo di dati di CassandraCassandra data type Tipo di dati provvisori di Data FactoryData factory interim data type
ASCIIASCII stringString
bigintBIGINT Int64Int64
BLOBBLOB Byte[]Byte[]
BOOLEANBOOLEAN BooleanBoolean
DECIMALDECIMAL DecimalDecimal
DOUBLEDOUBLE DoubleDouble
FLOATFLOAT SingoloSingle
INETINET stringString
INTINT Int32Int32
TEXTTEXT stringString
timestampTIMESTAMP Data e oraDateTime
TIMEUUIDTIMEUUID GUIDGuid
UUIDUUID GUIDGuid
VARCHARVARCHAR stringString
VARINTVARINT DecimalDecimal

Nota

Per i tipi di raccolta (mappa, set, elenco e così via), vedere la sezione Uso delle raccolte con una tabella virtuale .For collection types (map, set, list, etc.), refer to Work with Cassandra collection types using virtual table section.

I tipi definiti dall'utente non sono supportati.User-defined types are not supported.

La lunghezza di una colonna Binary o String non può essere maggiore di 4000.The length of Binary Column and String Column lengths cannot be greater than 4000.

Uso delle raccolte con una tabella virtualeWork with collections using virtual table

Azure Data Factory usa un driver ODBC integrato per connettersi ai dati di un database Cassandra e copiarli.Azure Data Factory uses a built-in ODBC driver to connect to and copy data from your Cassandra database. Per i tipi di raccolta, fra cui mappa, set ed elenco, il driver normalizza di nuovo i dati in tabelle virtuali corrispondenti.For collection types including map, set and list, the driver renormalizes the data into corresponding virtual tables. In particolare, se una tabella contiene colonne della raccolta, il driver genera le tabelle virtuali seguenti:Specifically, if a table contains any collection columns, the driver generates the following virtual tables:

  • Una tabella di baseche contiene gli stessi dati della tabella reale eccetto le colonne della raccolta.A base table, which contains the same data as the real table except for the collection columns. La tabella di base ha lo stesso nome della tabella reale che rappresenta.The base table uses the same name as the real table that it represents.
  • Una tabella virtuale per ogni colonna della raccolta che espande i dati nidificati.A virtual table for each collection column, which expands the nested data. Alle tabelle virtuali che rappresentano le raccolte vengono assegnati nomi composti dal nome della tabella reale seguito dal separatore "vt" e dal nome della colonna.The virtual tables that represent collections are named using the name of the real table, a separator "vt" and the name of the column.

Le tabelle virtuali fanno riferimento ai dati nella tabella reale, consentendo al driver di accedere ai dati denormalizzati.Virtual tables refer to the data in the real table, enabling the driver to access the denormalized data. Per i dettagli vedere la sezione Esempio.See Example section for details. È possibile accedere al contenuto delle raccolte Cassandra eseguendo query e join sulle tabelle virtuali.You can access the content of Cassandra collections by querying and joining the virtual tables.

EsempioExample

Ad esempio, "ExampleTable" è una tabella di un database Cassandra contenente una colonna chiave primaria integer denominata "pk_int", una colonna testo denominata value, una colonna elenco, una colonna mappa e una colonna set (denominata "StringSet").For example, the following "ExampleTable" is a Cassandra database table that contains an integer primary key column named "pk_int", a text column named value, a list column, a map column, and a set column (named "StringSet").

pk_intpk_int ValoreValue ElencoList MappaMap StringSetStringSet
11 "valore di esempio 1""sample value 1" ["1", "2", "3"]["1", "2", "3"] {"S1": "a", "S2": "b"}{"S1": "a", "S2": "b"} {"A", "B", "C"}{"A", "B", "C"}
33 "valore di esempio 3""sample value 3" ["100", "101", "102", "105"]["100", "101", "102", "105"] {"S1": "t"}{"S1": "t"} {"A", "E"}{"A", "E"}

Il driver genera più tabelle virtuali per rappresentare questa singola tabella.The driver would generate multiple virtual tables to represent this single table. Le colonne chiave esterna nelle tabelle virtuali fanno riferimento alle colonne chiave primaria nella tabella reale e indicano a quale riga della tabella reale corrisponde la riga della tabella virtuale.The foreign key columns in the virtual tables reference the primary key columns in the real table, and indicate which real table row the virtual table row corresponds to.

La prima tabella virtuale è la tabella di base denominata "ExampleTable", illustrata nell'esempio seguente:The first virtual table is the base table named "ExampleTable" is shown in the following table:

pk_intpk_int ValoreValue
11 "valore di esempio 1""sample value 1"
33 "valore di esempio 3""sample value 3"

La tabella di base contiene gli stessi dati della tabella di database originale, tranne le raccolte, che vengono omesse da questa tabella ed espanse in altre tabelle virtuali.The base table contains the same data as the original database table except for the collections, which are omitted from this table and expanded in other virtual tables.

Le tabelle seguenti illustrano le tabelle virtuali che normalizzano di nuovo i dati dalle colonne elenco, mappa e StringSet.The following tables show the virtual tables that renormalize the data from the List, Map, and StringSet columns. Le colonne con nomi che terminano con "_index" o "_key" indicano la posizione dei dati all'interno dell'elenco o della mappa originale.The columns with names that end with "_index" or "_key" indicate the position of the data within the original list or map. Le colonne con nomi che terminano con "_value" contengono i dati espansi dalla raccolta.The columns with names that end with "_value" contain the expanded data from the collection.

Tabella "ExampleTable_vt_List":Table "ExampleTable_vt_List":

pk_intpk_int List_indexList_index List_valueList_value
11 00 11
11 11 22
11 22 33
33 00 100100
33 11 101101
33 22 102102
33 33 103103

Tabella "ExampleTable_vt_Map":Table "ExampleTable_vt_Map":

pk_intpk_int Map_keyMap_key Map_valueMap_value
11 S1S1 AA
11 S2S2 bb
33 S1S1 tt

Tabella "ExampleTable_vt_StringSet":Table "ExampleTable_vt_StringSet":

pk_intpk_int StringSet_valueStringSet_value
11 AA
11 BB
11 CC
33 AA
33 EE

Proprietà attività di ricercaLookup activity properties

Per informazioni dettagliate sulle proprietà, controllare l' attività di ricerca.To learn details about the properties, check Lookup activity.

Passaggi successiviNext steps

Per un elenco degli archivi dati supportati come origini o sink dall'attività di copia in Azure Data Factory, vedere gli archivi dati supportati.For a list of data stores supported as sources and sinks by the copy activity in Azure Data Factory, see supported data stores.