Kopírování a transformace dat ve službě Azure Cosmos DB for NoSQL pomocí služby Azure Data Factory

PLATÍ PRO: Azure Data Factory Azure Synapse Analytics

Tento článek popisuje, jak pomocí aktivity kopírování ve službě Azure Data Factory kopírovat data z a do Azure Cosmos DB for NoSQL a jak pomocí Tok dat transformovat data ve službě Azure Cosmos DB for NoSQL. Další informace najdete v úvodních článcích pro Azure Data Factory a Azure Synapse Analytics.

Podporované funkce

Tento konektor Azure Cosmos DB for NoSQL je podporovaný pro následující funkce:

(1) Prostředí Azure Integration Runtime (2) Místní prostředí Integration Runtime

Pro aktivita Copy podporuje tento konektor Azure Cosmos DB for NoSQL:

• Kopírování dat z a do Azure Cosmos DB for NoSQL pomocí klíče, instančního objektu nebo spravovaných identit pro ověřování prostředků Azure
• Zápis do služby Azure Cosmos DB jako vložení nebo upsert
• Importujte a exportujte dokumenty JSON tak, jak jsou, nebo kopírujte data z tabulkové datové sady nebo do tabulkové datové sady. Mezi příklady patří databáze SQL a soubor CSV. Pokud chcete zkopírovat dokumenty tak, jak je, do souborů JSON nebo do jiné kolekce Azure Cosmos DB nebo z jiné kolekce Azure Cosmos DB, přečtěte si téma Import a export dokumentů JSON.

Kanály Služby Data Factory a Synapse se integrují s knihovnou bulk Executor služby Azure Cosmos DB, aby poskytovaly nejlepší výkon při zápisu do služby Azure Cosmos DB.

Začínáme

K provedení aktivita Copy s kanálem můžete použít jeden z následujících nástrojů nebo sad SDK:

• Nástroj pro kopírování dat
• Azure Portal
• Sada .NET SDK
• Sada Python SDK
• Azure PowerShell
• Rozhraní REST API
• Šablona Azure Resource Manageru

Vytvoření propojené služby se službou Azure Cosmos DB pomocí uživatelského rozhraní

Pomocí následujících kroků vytvořte propojenou službu se službou Azure Cosmos DB v uživatelském rozhraní webu Azure Portal.

1. Přejděte na kartu Správa v pracovním prostoru Azure Data Factory nebo Synapse a vyberte Propojené služby a pak klikněte na Nový:

   • Azure Data Factory
   • Azure Synapse

   

2. Vyhledejte Azure Cosmos DB for NoSQL a vyberte konektor Azure Cosmos DB for NoSQL.

   

3. Nakonfigurujte podrobnosti o službě, otestujte připojení a vytvořte novou propojenou službu.

   

Podrobnosti konfigurace konektoru

Následující části obsahují podrobnosti o vlastnostech, které můžete použít k definování entit specifických pro Azure Cosmos DB for NoSQL.

Vlastnosti propojené služby

Konektor Azure Cosmos DB for NoSQL podporuje následující typy ověřování. Podrobnosti najdete v odpovídajících částech:

• Ověřování pomocí klíče
• Ověřování instančních objektů
• Ověřování spravované identity přiřazené systémem
• Ověřování spravované identity přiřazené uživatelem

Ověřování pomocí klíče

Příklad

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Příklad: Uložení klíče účtu ve službě Azure Key Vault

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "connectionString": "AccountEndpoint=<EndpointUrl>;Database=<Database>",
            "accountKey": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<Azure Key Vault linked service name>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<secretName>" 
            }
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ověřování instančního objektu

Pokud chcete použít ověřování instančního objektu, postupujte takto.

1. Zaregistrujte aplikaci na platformě Microsoft Identity Platform. Postup najdete v tématu Rychlý start: Registrace aplikace na platformě Microsoft Identity Platform. Poznamenejte si tyto hodnoty, které použijete k definování propojené služby:

   • ID aplikace
   • Klíč aplikace
   • ID tenanta

2. Udělte instančnímu objektu správné oprávnění. Podívejte se na příklady fungování oprávnění ve službě Azure Cosmos DB ze seznamů řízení přístupu u souborů a adresářů. Konkrétněji vytvořte definici role a přiřaďte roli instančnímu objektu prostřednictvím ID instančního objektu.

Propojená služba podporuje tyto vlastnosti:

Příklad: Použití ověřování pomocí instančního klíče

Ve službě Azure Key Vault můžete také uložit instanční klíč.

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalKey",
            "servicePrincipalCredential": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Příklad: Použití ověřování certifikátů instančního objektu

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>", 
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalCredential": { 
                "type": "AzureKeyVaultSecret", 
                "store": { 
                    "referenceName": "<AKV reference>", 
                    "type": "LinkedServiceReference" 
                }, 
                "secretName": "<certificate name in AKV>" 
            },
            "tenant": "<tenant info, e.g. microsoft.onmicrosoft.com>" 
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ověřování spravované identity přiřazené systémem

Datovou továrnu nebo kanál Synapse je možné přidružit ke spravované identitě přiřazené systémem pro prostředky Azure, což představuje tuto konkrétní instanci služby. Tuto spravovanou identitu můžete použít přímo pro ověřování azure Cosmos DB, podobně jako u vlastního instančního objektu. Umožňuje tomuto určenému prostředku přístup k datům a jejich kopírování do nebo z vaší instance služby Azure Cosmos DB.

Pokud chcete pro ověřování prostředků Azure použít spravované identity přiřazené systémem, postupujte podle těchto kroků.

1. Načtěte informace o spravované identitě přiřazené systémem zkopírováním hodnoty ID objektu spravované identity vygenerované společně s vaší službou.

2. Udělte spravované identitě přiřazené systémem správné oprávnění. Podívejte se na příklady fungování oprávnění ve službě Azure Cosmos DB ze seznamů řízení přístupu u souborů a adresářů. Konkrétněji vytvořte definici role a přiřaďte ji spravované identitě přiřazené systémem.

Propojená služba podporuje tyto vlastnosti:

Příklad:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Ověřování spravované identity přiřazené uživatelem

Datovou továrnu nebo kanál Synapse je možné přidružit ke spravovaným identitám přiřazeným uživatelem, což představuje tuto konkrétní instanci služby. Tuto spravovanou identitu můžete použít přímo pro ověřování azure Cosmos DB, podobně jako u vlastního instančního objektu. Umožňuje tomuto určenému prostředku přístup k datům a jejich kopírování do nebo z vaší instance služby Azure Cosmos DB.

Pokud chcete pro ověřování prostředků Azure používat spravované identity přiřazené uživatelem, postupujte podle těchto kroků.

1. Vytvořte jednu nebo více spravovaných identit přiřazených uživatelem a udělte spravované identitě přiřazené uživatelem správné oprávnění. Podívejte se na příklady fungování oprávnění ve službě Azure Cosmos DB ze seznamů řízení přístupu u souborů a adresářů. Konkrétněji vytvořte definici role a přiřaďte ji spravované identitě přiřazené uživatelem.

2. Přiřaďte k datové továrně jednu nebo více spravovaných identit přiřazených uživatelem a vytvořte přihlašovací údaje pro každou spravovanou identitu přiřazenou uživatelem.

Propojená služba podporuje tyto vlastnosti:

Příklad:

{
    "name": "CosmosDbSQLAPILinkedService",
    "properties": {
        "type": "CosmosDb",
        "typeProperties": {
            "accountEndpoint": "<account endpoint>",
            "database": "<database name>",
            "credential": {
                "referenceName": "credential1",
                "type": "CredentialReference"
            },
            "subscriptionId": "<subscription id>",
            "tenantId": "<tenant id>",
            "resourceGroup": "<resource group>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Vlastnosti datové sady

Úplný seznam oddílů a vlastností, které jsou k dispozici pro definování datových sad, najdete v tématu Datové sady a propojené služby.

Pro datovou sadu Azure Cosmos DB for NoSQL se podporují následující vlastnosti:

Pokud používáte datovou sadu typu DocumentDbCollection, je stále podporovaná tak, jak je pro zpětnou kompatibilitu aktivity kopírování a vyhledávání, není podporována pro Tok dat. Doporučujeme používat nový model v budoucnu.

Příklad

{
    "name": "CosmosDbSQLAPIDataset",
    "properties": {
        "type": "CosmosDbSqlApiCollection",
        "linkedServiceName":{
            "referenceName": "<Azure Cosmos DB linked service name>",
            "type": "LinkedServiceReference"
        },
        "schema": [],
        "typeProperties": {
            "collectionName": "<collection name>"
        }
    }
}

Vlastnosti aktivity kopírování

Tato část obsahuje seznam vlastností, které podporuje zdroj a jímka Azure Cosmos DB for NoSQL. Úplný seznam oddílů a vlastností, které jsou k dispozici pro definování aktivit, najdete v tématu Kanály.

Azure Cosmos DB for NoSQL jako zdroj

Pokud chcete kopírovat data ze služby Azure Cosmos DB for NoSQL, nastavte typ zdroje v aktivitě kopírování na DocumentDbCollectionSource.

Ve zdroji aktivity kopírování jsou podporovány následující vlastnosti:

Pokud používáte zdroj typu DocumentDbCollectionSource, je stále podporován tak, jak je to kvůli zpětné kompatibilitě. Doporučujeme použít nový model, který bude poskytovat bohatší možnosti kopírování dat ze služby Azure Cosmos DB.

Příklad

"activities":[
    {
        "name": "CopyFromCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<Cosmos DB for NoSQL input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "CosmosDbSqlApiSource",
                "query": "SELECT c.BusinessEntityID, c.Name.First AS FirstName, c.Name.Middle AS MiddleName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"",
                "preferredRegions": [
                    "East US"
                ]
            },
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Při kopírování dat ze služby Azure Cosmos DB, pokud nechcete exportovat dokumenty JSON tak, jak je, je osvědčeným postupem určit mapování v aktivitě kopírování. Služba respektuje mapování, které jste zadali v aktivitě – pokud řádek neobsahuje hodnotu sloupce, je pro hodnotu sloupce zadána hodnota null. Pokud neurčíte mapování, služba odvodí schéma pomocí prvního řádku dat. Pokud první řádek neobsahuje úplné schéma, některé sloupce nebudou ve výsledku operace aktivity chybět.

Azure Cosmos DB for NoSQL jako jímka

Pokud chcete kopírovat data do služby Azure Cosmos DB for NoSQL, nastavte typ jímky v aktivitě kopírování na DocumentDbCollectionSink.

V části Jímka aktivity kopírování se podporují následující vlastnosti:

Pokud používáte zdroj typu DocumentDbCollectionSink, je stále podporován, protože je pro zpětnou kompatibilitu. Doporučujeme použít nový model, který bude poskytovat bohatší možnosti kopírování dat ze služby Azure Cosmos DB.

Příklad

"activities":[
    {
        "name": "CopyToCosmosDBSQLAPI",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<Document DB output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "<source type>"
            },
            "sink": {
                "type": "CosmosDbSqlApiSink",
                "writeBehavior": "upsert"
            }
        }
    }
]

Schema mapping

Pokud chcete kopírovat data ze služby Azure Cosmos DB do tabulkové jímky nebo obráceně, přečtěte si mapování schématu.

Mapování vlastností toku dat

Při transformaci dat při mapování toku dat můžete číst a zapisovat do kolekcí ve službě Azure Cosmos DB. Další informace najdete v tématu transformace zdroje a transformace jímky v mapování toků dat.

Transformace zdroje

Nastavení specifická pro Službu Azure Cosmos DB jsou k dispozici na kartě Možnosti zdroje transformace zdroje.

Zahrnout systémové sloupce: Pokud je true, ida _tsdalší systémové sloupce budou zahrnuty do metadat toku dat ze služby Azure Cosmos DB. Při aktualizaci kolekcí je důležité tuto možnost zahrnout, abyste mohli získat ID existujícího řádku.

Velikost stránky: Počet dokumentů na stránku výsledku dotazu. Výchozí hodnota je -1, která používá dynamickou stránku služby až 1 000.

Propustnost: Nastavte volitelnou hodnotu pro počet RU, které chcete použít pro kolekci Azure Cosmos DB pro každé spuštění tohoto toku dat během operace čtení. Minimum je 400.

Upřednostňované oblasti: Zvolte upřednostňované oblasti čtení pro tento proces.

Kanál změn: Pokud ano, získáte data z kanálu změn služby Azure Cosmos DB, což je trvalý záznam změn v kontejneru v pořadí, v jakém k nim dochází z posledního spuštění automaticky. Pokud nastavíte hodnotu true, nenastavujte oba typy odvozovaných sloupců a Povolit posun schématu ve stejnou dobu jako true. Další podrobnosti najdete v kanálu změn služby Azure Cosmos DB).

Začněte od začátku: Pokud je true, získáte počáteční načtení úplných dat snímků při prvním spuštění a zachytávání změněných dat v dalších spuštěních. Pokud je false, počáteční načtení se při prvním spuštění přeskočí a následně zachytí změněná data v dalších spuštěních. Nastavení je v referenčních informacích ke službě Azure Cosmos DB zarovnané se stejným názvem nastavení. Další podrobnosti najdete v kanálu změn služby Azure Cosmos DB.

Transformace jímky

Nastavení specifická pro Službu Azure Cosmos DB jsou k dispozici na kartě Nastavení transformace jímky.

Metoda aktualizace: Určuje, jaké operace jsou povoleny v cíli databáze. Výchozí hodnota je povolit pouze vkládání. Pokud chcete aktualizovat, upsertovat nebo odstranit řádky, je pro tyto akce potřeba transformace alter-row. Pro aktualizace, upserty a odstranění je nutné nastavit klíčový sloupec nebo sloupce, aby bylo možné určit, který řádek se má změnit.

Akce kolekce: Určuje, zda se má cílová kolekce vytvořit před zápisem.

• Žádné: V kolekci se neprovede žádná akce.
• Znovu vytvořte: Kolekce se zahodí a znovu vytvoří.

Velikost dávky: Celé číslo, které představuje, kolik objektů se zapisuje do kolekce Azure Cosmos DB v každé dávce. Obvykle stačí začít s výchozí velikostí dávky. Pokud chcete tuto hodnotu dále vyladit, mějte na paměti:

• Azure Cosmos DB omezuje velikost jednoho požadavku na 2 MB. Vzorec je "Request Size = Single Document Size * Batch Size". Pokud dojde k chybě s informacemi o tom, že je velikost požadavku příliš velká, zmenšete hodnotu velikosti dávky.
• Čím větší je velikost dávky, tím vyšší propustnost může služba dosáhnout, a zároveň se ujistěte, že přidělujete dostatek RU, aby vaše úloha zajistila.

Klíč oddílu: Zadejte řetězec, který představuje klíč oddílu pro vaši kolekci. Příklad: /movies/title

Propustnost: Nastavte volitelnou hodnotu pro počet RU, které chcete použít pro kolekci Azure Cosmos DB pro každé spuštění tohoto toku dat. Minimum je 400.

Rozpočet propustnosti zápisu: Celé číslo, které představuje jednotky RU, které chcete pro tuto operaci Tok dat zápisu přidělit, z celkové propustnosti přidělené kolekci.

Vlastnosti aktivity vyhledávání

Podrobnosti o vlastnostech najdete v aktivitě Vyhledávání.

Import a export dokumentů JSON

Pomocí tohoto konektoru Azure Cosmos DB for NoSQL můžete snadno:

• Kopírování dokumentů mezi dvěma kolekcemi Azure Cosmos DB tak, jak je.
• Importujte dokumenty JSON z různých zdrojů do služby Azure Cosmos DB, včetně z Úložiště objektů blob v Azure, Azure Data Lake Store a dalších úložišť založených na souborech, které služba podporuje.
• Exportujte dokumenty JSON z kolekce Azure Cosmos DB do různých souborových úložišť.

Chcete-li dosáhnout kopírování nezávislé na schématu:

• Když použijete nástroj Pro kopírování dat, vyberte možnost Exportovat jako do souborů JSON nebo kolekce Azure Cosmos DB.
• Při vytváření aktivit zvolte formát JSON s odpovídajícím úložištěm souborů pro zdroj nebo jímku.

Migrace z relační databáze do služby Azure Cosmos DB

Při migraci z relační databáze e.g. SQL Serveru do Služby Azure Cosmos DB může aktivita kopírování snadno mapovat tabulková data ze zdroje na zploštěné dokumenty JSON ve službě Azure Cosmos DB. V některých případech můžete chtít datový model přepracovat tak, aby ho optimalizoval pro případy použití NoSQL v závislosti na modelování dat ve službě Azure Cosmos DB, například tak, aby se data de normalizovala vložením všech souvisejících dílčích položek do jednoho dokumentu JSON. V takovém případě si projděte tento článek s návodem k jeho dosažení pomocí aktivity kopírování.

Kanál změn ve službě Azure Cosmos DB

Azure Data Factory může získat data z kanálu změn služby Azure Cosmos DB tím, že je povolí v transformaci zdroje toku dat mapování. Pomocí této možnosti konektoru si můžete přečíst kanály změn a použít transformace před načtením transformovaných dat do cílových datových sad podle vašeho výběru. Ke čtení kanálu změn a následnému zápisu vlastních transformací nemusíte používat funkce Azure Functions. Tuto možnost můžete použít k přesunu dat z jednoho kontejneru do druhého, přípravě zobrazení materiálů řízených kanálem změn pro účely nebo automatizaci zálohování nebo obnovení kontejnerů na základě kanálu změn a povolení mnoha dalších takových případů použití pomocí vizuálního přetažení a vyřazení funkce Azure Data Factory.

Ujistěte se, že název kanálu a aktivity zůstane beze změny, aby bylo možné kontrolní bod zaznamenat službou ADF, abyste získali změněná data z posledního spuštění automaticky. Pokud změníte název kanálu nebo název aktivity, kontrolní bod se resetuje, což vede k tomu, že v dalším běhu začnete od začátku nebo se změny provedou od nynějška.

Při ladění kanálu funguje tato funkce stejně. Mějte na paměti, že kontrolní bod se resetuje při aktualizaci prohlížeče během spuštění ladění. Jakmile budete spokojeni s výsledkem kanálu spuštění ladění, můžete pokračovat v publikování a aktivaci kanálu. V okamžiku, kdy poprvé aktivujete publikovaný kanál, se automaticky restartuje od začátku nebo od této chvíle dojde ke změnám.

V části monitorování máte vždy možnost znovu spustit kanál. Když to uděláte, změněná data se vždy zaznamenávají z předchozího kontrolního bodu vybraného kanálu.

Analytické úložiště Azure Cosmos DB teď navíc podporuje funkci Change Data Capture (CDC) pro rozhraní API služby Azure Cosmos DB pro NoSQL a rozhraní API služby Azure Cosmos DB pro Mongo DB (public Preview). Analytické úložiště Azure Cosmos DB umožňuje efektivně využívat průběžný a přírůstkový kanál změněných (vložených, aktualizovaných a odstraněných) dat z analytického úložiště.

Související obsah

Seznam úložišť dat, která aktivita kopírování podporuje jako zdroje a jímky, najdete v podporovaných úložištích dat.