Gegevens verplaatsen van en naar Azure Cosmos DB met behulp van Azure Data Factory

Notitie

Dit artikel is van toepassing op versie 1 van Data Factory. Als u de huidige versie van de Data Factory-service gebruikt, raadpleegt u de Azure Cosmos DB-connector in V2.

In dit artikel wordt uitgelegd hoe u de kopieeractiviteit in Azure Data Factory kunt gebruiken om gegevens te verplaatsen naar/van Azure Cosmos DB (SQL API). Het bouwt voort op het artikel Gegevensverplaatsingsactiviteiten , waarin een algemeen overzicht van gegevensverplaatsing met de kopieeractiviteit wordt gepresenteerd.

U kunt gegevens kopiëren uit elk ondersteund brongegevensarchief naar Azure Cosmos DB of van Azure Cosmos DB naar elk ondersteund sinkgegevensarchief. Zie de tabel Ondersteunde gegevensarchieven voor een lijst met gegevensarchieven die worden ondersteund als bronnen of sinks door de kopieeractiviteit.

Belangrijk

Azure Cosmos DB-connector ondersteunt alleen de SQL-API.

Zie Import/Export JSON-documenten als u gegevens naar/van JSON-bestanden of een andere Cosmos DB-verzameling wilt kopiëren.

Aan de slag

U kunt een pijplijn maken met een kopieeractiviteit waarmee gegevens worden verplaatst naar/van Azure Cosmos DB met behulp van verschillende hulpprogramma's/API's.

De eenvoudigste manier om een pijplijn te maken, is door de wizard Kopiëren te gebruiken. Zie Zelfstudie: Een pijplijn maken met de wizard Kopiëren voor een beknopt overzicht van het maken van een pijplijn met behulp van de wizard Gegevens kopiëren.

U kunt ook de volgende hulpprogramma's gebruiken om een pijplijn te maken: Visual Studio, Azure PowerShell, Azure Resource Manager-sjabloon, .NET API en REST API. Zie Copy-activiteit zelfstudie voor stapsgewijze instructies voor het maken van een pijplijn met een kopieeractiviteit.

Of u nu de hulpprogramma's of API's gebruikt, u voert de volgende stappen uit om een pijplijn te maken waarmee gegevens uit een brongegevensarchief worden verplaatst naar een sinkgegevensarchief:

  1. Maak gekoppelde services om invoer- en uitvoergegevensarchieven te koppelen aan uw data factory.
  2. Gegevenssets maken om invoer- en uitvoergegevens voor de kopieerbewerking weer te geven.
  3. Maak een pijplijn met een kopieeractiviteit die een gegevensset als invoer en een gegevensset als uitvoer gebruikt.

Wanneer u de wizard gebruikt, worden JSON-definities voor deze Data Factory-entiteiten (gekoppelde services, gegevenssets en de pijplijn) automatisch voor u gemaakt. Wanneer u hulpprogramma's/API's (met uitzondering van .NET API) gebruikt, definieert u deze Data Factory-entiteiten met behulp van de JSON-indeling. Zie de sectie JSON-voorbeelden van dit artikel voor voorbeelden met JSON-definities voor Data Factory-entiteiten die worden gebruikt voor het kopiëren van gegevens naar/van Cosmos DB.

De volgende secties bevatten details over JSON-eigenschappen die worden gebruikt om Data Factory-entiteiten te definiëren die specifiek zijn voor Cosmos DB:

Eigenschappen van gekoppelde service

De volgende tabel bevat een beschrijving voor JSON-elementen die specifiek zijn voor de gekoppelde Azure Cosmos DB-service.

Eigenschap Beschrijving Vereist
type De typeeigenschap moet worden ingesteld op: DocumentDb Ja
connectionString Geef informatie op die nodig is om verbinding te maken met de Azure Cosmos DB-database. Yes

Voorbeeld:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

Eigenschappen van gegevensset

Raadpleeg het artikel Gegevenssets maken voor een volledige lijst met sectie-eigenschappen & die beschikbaar zijn voor het definiëren van gegevenssets. Secties zoals structuur, beschikbaarheid en beleid van een gegevensset JSON zijn vergelijkbaar voor alle typen gegevenssets (Azure SQL, Azure Blob, Azure-tabel, enzovoort).

De sectie typeProperties verschilt voor elk type gegevensset en bevat informatie over de locatie van de gegevens in het gegevensarchief. De sectie typeProperties voor de gegevensset van het type DocumentDbCollection heeft de volgende eigenschappen.

Eigenschap Beschrijving Vereist
collectionName Naam van de Cosmos DB-documentverzameling. Yes

Voorbeeld:

{
  "name": "PersonCosmosDbTable",
  "properties": {
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Schema per Data Factory

Voor schemavrije gegevensarchieven zoals Azure Cosmos DB leidt de Data Factory-service het schema op een van de volgende manieren af:

  1. Als u de structuur van gegevens opgeeft met behulp van de structuureigenschap in de definitie van de gegevensset, wordt deze structuur door de Data Factory-service als schema gehonoreerd. Als een rij in dit geval geen waarde voor een kolom bevat, wordt er een null-waarde opgegeven.
  2. Als u de structuur van gegevens niet opgeeft met behulp van de structuureigenschap in de definitie van de gegevensset, wordt het schema door de Data Factory-service afgeleid met behulp van de eerste rij in de gegevens. Als de eerste rij in dit geval niet het volledige schema bevat, ontbreken sommige kolommen in het resultaat van de kopieerbewerking.

Daarom is voor gegevensbronnen zonder schema de best practice om de structuur van gegevens op te geven met behulp van de structuureigenschap .

Eigenschappen van de kopieeractiviteit

Raadpleeg het artikel Pijplijnen maken voor een volledige lijst met sectie-eigenschappen & die beschikbaar zijn voor het definiëren van activiteiten. Eigenschappen zoals naam, beschrijving, invoer- en uitvoertabellen en beleid zijn beschikbaar voor alle typen activiteiten.

Notitie

De kopieeractiviteit heeft slechts één invoer en produceert slechts één uitvoer.

Eigenschappen die beschikbaar zijn in de sectie typeProperties van de activiteit daarentegen variëren met elk activiteitstype en in het geval van Copy-activiteit ze variëren, afhankelijk van de typen bronnen en sinks.

In het geval van Copy-activiteit wanneer de bron van het type DocumentDbCollectionSource is, zijn de volgende eigenschappen beschikbaar in de sectie typeProperties:

Eigenschap Beschrijving Toegestane waarden Vereist
query Geef de query op om gegevens te lezen. Queryreeks die wordt ondersteund door Azure Cosmos DB.

Voorbeeld: SELECT c.BusinessEntityID, c.PersonType, c.NameStyle, c.Title, c.Name.First AS FirstName, c.Name.Last AS LastName, c.Suffix, c.EmailPromotion FROM c WHERE c.ModifiedDate > \"2009-01-01T00:00:00\"
No

Als dit niet is opgegeven, wordt de SQL instructie uitgevoerd:select <columns defined in structure> from mycollection
nestingSeparator Speciaal teken om aan te geven dat het document is genest Elk teken.

Azure Cosmos DB is een NoSQL-archief voor JSON-documenten, waarbij geneste structuren zijn toegestaan. Azure Data Factory stelt de gebruiker in staat om hiërarchie aan te geven via nestingSeparator. Dit is '.' in de bovenstaande voorbeelden. Met het scheidingsteken genereert de kopieeractiviteit het object 'Naam' met drie onderliggende elementen Voor- en Midden- en Achternaam, volgens 'Name.First', 'Name.Middle' en 'Name.Last' in de tabeldefinitie.
No

DocumentDbCollectionSink ondersteunt de volgende eigenschappen:

Eigenschap Beschrijving Toegestane waarden Vereist
nestingSeparator Een speciaal teken in de naam van de bronkolom om aan te geven dat genest document nodig is.

Bijvoorbeeld hierboven: Name.First in de uitvoertabel produceert u de volgende JSON-structuur in het Cosmos DB-document:

"Naam": {
"Eerste": "John"
},
Teken dat wordt gebruikt voor het scheiden van geneste niveaus.

De standaardwaarde is . (punt).
Teken dat wordt gebruikt voor het scheiden van geneste niveaus.

De standaardwaarde is . (punt).
writeBatchSize Het aantal parallelle aanvragen voor de Azure Cosmos DB-service om documenten te maken.

U kunt de prestaties verfijnen bij het kopiëren van gegevens naar/van Cosmos DB met behulp van deze eigenschap. U kunt een betere prestaties verwachten wanneer u writeBatchSize verhoogt omdat er meer parallelle aanvragen naar Cosmos DB worden verzonden. U moet echter beperking voorkomen die het foutbericht kan veroorzaken: 'Aanvraagsnelheid is groot'.

Beperking wordt bepaald door een aantal factoren, waaronder de grootte van documenten, het aantal termen in documenten, het indexeringsbeleid van de doelverzameling, enzovoort. Voor kopieerbewerkingen kunt u een betere verzameling (bijvoorbeeld S3) gebruiken om de meeste doorvoer beschikbaar te hebben (2500 aanvraageenheden/seconde).
Geheel getal Nee (standaard: 5)
writeBatchTimeout Wachttijd voordat de bewerking is voltooid voordat er een time-out optreedt. tijdsbestek

Voorbeeld: "00:30:00" (30 minuten).
No

JSON-documenten Import/Export

Met deze Cosmos DB-connector kunt u eenvoudig

  • Importeer JSON-documenten uit verschillende bronnen in Cosmos DB, waaronder Azure Blob, Azure Data Lake, on-premises bestandssysteem of andere op bestanden gebaseerde archieven die worden ondersteund door Azure Data Factory.
  • Exporteer JSON-documenten uit de Cosmos DB-verzameling naar verschillende bestandsarchieven.
  • Gegevens migreren tussen twee Cosmos DB-verzamelingen.

Om een dergelijke schema-agnostische kopie te bereiken,

  • Wanneer u de wizard Kopiëren gebruikt, schakelt u de optie Exporteren naar JSON-bestanden of Cosmos DB-verzameling in .
  • Wanneer u JSON-bewerking gebruikt, geeft u niet de sectie 'structuur' op in cosmos DB-gegevensset(s) of de eigenschap nestingSeparator op cosmos DB-bron/sink in kopieeractiviteit. Als u wilt importeren van/exporteren naar JSON-bestanden, geeft u in de gegevensset van het bestandsarchief het indelingstype 'JsonFormat' op, configureert u filePattern en slaat u de restindelingsinstellingen over. Zie de sectie JSON-indeling voor meer informatie.

JSON-voorbeelden

De volgende voorbeelden bevatten voorbeeld-JSON-definities die u kunt gebruiken om een pijplijn te maken met behulp van Visual Studio of Azure PowerShell. Ze laten zien hoe u gegevens kopieert van en naar Azure Cosmos DB en Azure Blob Storage. Gegevens kunnen echter rechtstreeks vanuit een van de bronnen naar een van de sinks worden gekopieerd die hier worden vermeld met behulp van de kopieeractiviteit in Azure Data Factory.

Voorbeeld: Gegevens kopiëren van Azure Cosmos DB naar Azure Blob

In het onderstaande voorbeeld ziet u:

  1. Een gekoppelde service van het type DocumentDb.
  2. Een gekoppelde service van het type AzureStorage.
  3. Een invoergegevensset van het type DocumentDbCollection.
  4. Een uitvoergegevensset van het type AzureBlob.
  5. Een pijplijn met kopieeractiviteit die gebruikmaakt van DocumentDbCollectionSource en BlobSink.

In het voorbeeld worden gegevens in Azure Cosmos DB gekopieerd naar Azure Blob. De JSON-eigenschappen die in deze voorbeelden worden gebruikt, worden beschreven in secties na de voorbeelden.

Gekoppelde Azure Cosmos DB-service:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

Gekoppelde Azure Blob Storage-service:

{
  "name": "StorageLinkedService",
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
    }
  }
}

Azure Document DB-invoergegevensset:

In het voorbeeld wordt ervan uitgegaan dat u een verzameling hebt met de naam Persoon in een Azure Cosmos DB-database.

Instelling 'extern': 'true' en het opgeven van externegegevensbeleidsgegevens de Azure Data Factory-service die de tabel extern is voor de data factory en niet wordt geproduceerd door een activiteit in de data factory.

{
  "name": "PersonCosmosDbTable",
  "properties": {
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Azure Blob-uitvoergegevensset:

Gegevens worden elk uur gekopieerd naar een nieuwe blob met het pad voor de blob die de specifieke datum/tijd weergeeft met granulariteit per uur.

{
  "name": "PersonBlobTableOut",
  "properties": {
    "type": "AzureBlob",
    "linkedServiceName": "StorageLinkedService",
    "typeProperties": {
      "folderPath": "docdb",
      "format": {
        "type": "TextFormat",
        "columnDelimiter": ",",
        "nullValue": "NULL"
      }
    },
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Voorbeeld van een JSON-document in de verzameling Persoon in een Cosmos DB-database:

{
  "PersonId": 2,
  "Name": {
    "First": "Jane",
    "Middle": "",
    "Last": "Doe"
  }
}

Cosmos DB biedt ondersteuning voor het uitvoeren van query's op documenten met behulp van een SQL zoals syntaxis voor hiërarchische JSON-documenten.

Voorbeeld:

SELECT Person.PersonId, Person.Name.First AS FirstName, Person.Name.Middle as MiddleName, Person.Name.Last AS LastName FROM Person

Met de volgende pijplijn worden gegevens gekopieerd van de verzameling Persoon in de Azure Cosmos DB-database naar een Azure-blob. Als onderdeel van de kopieeractiviteit zijn de invoer- en uitvoergegevenssets opgegeven.

{
  "name": "DocDbToBlobPipeline",
  "properties": {
    "activities": [
      {
        "type": "Copy",
        "typeProperties": {
          "source": {
            "type": "DocumentDbCollectionSource",
            "query": "SELECT Person.Id, Person.Name.First AS FirstName, Person.Name.Middle as MiddleName, Person.Name.Last AS LastName FROM Person",
            "nestingSeparator": "."
          },
          "sink": {
            "type": "BlobSink",
            "blobWriterAddHeader": true,
            "writeBatchSize": 1000,
            "writeBatchTimeout": "00:00:59"
          }
        },
        "inputs": [
          {
            "name": "PersonCosmosDbTable"
          }
        ],
        "outputs": [
          {
            "name": "PersonBlobTableOut"
          }
        ],
        "policy": {
          "concurrency": 1
        },
        "name": "CopyFromDocDbToBlob"
      }
    ],
    "start": "2015-04-01T00:00:00Z",
    "end": "2015-04-02T00:00:00Z"
  }
}

Voorbeeld: Gegevens kopiëren van Azure Blob naar Azure Cosmos DB

In het onderstaande voorbeeld ziet u:

  1. Een gekoppelde service van het type DocumentDb.
  2. Een gekoppelde service van het type AzureStorage.
  3. Een invoergegevensset van het type AzureBlob.
  4. Een uitvoergegevensset van het type DocumentDbCollection.
  5. Een pijplijn met kopieeractiviteit die gebruikmaakt van BlobSource en DocumentDbCollectionSink.

In het voorbeeld worden gegevens gekopieerd van Azure Blob naar Azure Cosmos DB. De JSON-eigenschappen die in deze voorbeelden worden gebruikt, worden beschreven in secties na de voorbeelden.

Gekoppelde Azure Blob Storage-service:

{
  "name": "StorageLinkedService",
  "properties": {
    "type": "AzureStorage",
    "typeProperties": {
      "connectionString": "DefaultEndpointsProtocol=https;AccountName=<accountname>;AccountKey=<accountkey>"
    }
  }
}

Gekoppelde Azure Cosmos DB-service:

{
  "name": "CosmosDbLinkedService",
  "properties": {
    "type": "DocumentDb",
    "typeProperties": {
      "connectionString": "AccountEndpoint=<EndpointUrl>;AccountKey=<AccessKey>;Database=<Database>"
    }
  }
}

Azure Blob-invoergegevensset:

{
  "name": "PersonBlobTableIn",
  "properties": {
    "structure": [
      {
        "name": "Id",
        "type": "Int"
      },
      {
        "name": "FirstName",
        "type": "String"
      },
      {
        "name": "MiddleName",
        "type": "String"
      },
      {
        "name": "LastName",
        "type": "String"
      }
    ],
    "type": "AzureBlob",
    "linkedServiceName": "StorageLinkedService",
    "typeProperties": {
      "fileName": "input.csv",
      "folderPath": "docdb",
      "format": {
        "type": "TextFormat",
        "columnDelimiter": ",",
        "nullValue": "NULL"
      }
    },
    "external": true,
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Uitvoergegevensset van Azure Cosmos DB:

In het voorbeeld worden gegevens gekopieerd naar een verzameling met de naam 'Persoon'.

{
  "name": "PersonCosmosDbTableOut",
  "properties": {
    "structure": [
      {
        "name": "Id",
        "type": "Int"
      },
      {
        "name": "Name.First",
        "type": "String"
      },
      {
        "name": "Name.Middle",
        "type": "String"
      },
      {
        "name": "Name.Last",
        "type": "String"
      }
    ],
    "type": "DocumentDbCollection",
    "linkedServiceName": "CosmosDbLinkedService",
    "typeProperties": {
      "collectionName": "Person"
    },
    "availability": {
      "frequency": "Day",
      "interval": 1
    }
  }
}

Met de volgende pijplijn worden gegevens gekopieerd van Azure Blob naar de verzameling Persoon in Cosmos DB. Als onderdeel van de kopieeractiviteit zijn de invoer- en uitvoergegevenssets opgegeven.

{
  "name": "BlobToDocDbPipeline",
  "properties": {
    "activities": [
      {
        "type": "Copy",
        "typeProperties": {
          "source": {
            "type": "BlobSource"
          },
          "sink": {
            "type": "DocumentDbCollectionSink",
            "nestingSeparator": ".",
            "writeBatchSize": 2,
            "writeBatchTimeout": "00:00:00"
          },
          "translator": {
              "type": "TabularTranslator",
              "ColumnMappings": "FirstName: Name.First, MiddleName: Name.Middle, LastName: Name.Last, BusinessEntityID: BusinessEntityID, PersonType: PersonType, NameStyle: NameStyle, Title: Title, Suffix: Suffix, EmailPromotion: EmailPromotion, rowguid: rowguid, ModifiedDate: ModifiedDate"
          }
        },
        "inputs": [
          {
            "name": "PersonBlobTableIn"
          }
        ],
        "outputs": [
          {
            "name": "PersonCosmosDbTableOut"
          }
        ],
        "policy": {
          "concurrency": 1
        },
        "name": "CopyFromBlobToDocDb"
      }
    ],
    "start": "2015-04-14T00:00:00Z",
    "end": "2015-04-15T00:00:00Z"
  }
}

Als de voorbeeldblobinvoer is zoals

1,John,,Doe

Vervolgens is de uitvoer-JSON in Cosmos DB als:

{
  "Id": 1,
  "Name": {
    "First": "John",
    "Middle": null,
    "Last": "Doe"
  },
  "id": "a5e8595c-62ec-4554-a118-3940f4ff70b6"
}

Azure Cosmos DB is een NoSQL-archief voor JSON-documenten, waarbij geneste structuren zijn toegestaan. Azure Data Factory stelt de gebruiker in staat om de hiërarchie aan te geven via nestingSeparator, dat in dit voorbeeld '.' is. Met het scheidingsteken genereert de kopieeractiviteit het object 'Naam' met drie onderliggende elementen Voor- en Midden- en Achternaam, volgens 'Name.First', 'Name.Middle' en 'Name.Last' in de tabeldefinitie.

Bijlage

  1. Vraag: Ondersteunt de kopieeractiviteit update van bestaande records?

    Antwoord: Nee.

  2. Vraag: Hoe wordt een kopie opnieuw geprobeerd naar Azure Cosmos DB om te gaan met al gekopieerde records?

    Antwoord: Als records een id-veld hebben en de kopieerbewerking probeert een record met dezelfde id in te voegen, genereert de kopieerbewerking een fout.

  3. Vraag: Ondersteunt Data Factory bereik- of hashgebaseerde gegevenspartitionering?

    Antwoord: Nee.

  4. Vraag: Kan ik meer dan één Azure Cosmos DB-verzameling voor een tabel opgeven?

    Antwoord: Nee. Op dit moment kan slechts één verzameling worden opgegeven.

Prestaties en afstemming

Zie de handleiding voor het afstemmen van de prestaties & van kopieeractiviteiten voor meer informatie over belangrijke factoren die van invloed zijn op de prestaties van gegevensverplaatsing (kopieeractiviteit) in Azure Data Factory en op verschillende manieren om deze te optimaliseren.