Az alkalmazás migrálása az Azure Cosmos DB Java SDK v4 használatára

  • Cikk

A KÖVETKEZŐRE VONATKOZIK: NoSQL

Fontos

Az SDK-val kapcsolatos további információkért tekintse meg az Azure Cosmos DB Java SDK v4 kibocsátási megjegyzéseit, a Maven-adattárat, az Azure Cosmos DB Java SDK v4 teljesítménytippeket és az Azure Cosmos DB Java SDK v4 hibaelhárítási útmutatóját.

Fontos

Mivel az Azure Cosmos DB Java SDK v4 akár 20%-kal megnövelt átviteli sebességgel, TCP-alapú közvetlen móddal és a legújabb háttérszolgáltatás-funkciók támogatásával rendelkezik, javasoljuk, hogy a következő lehetőségnél frissítsen a v4-re. További információért olvassa el az alábbi szakaszt.

Frissítsen a legújabb Azure Cosmos DB Java SDK-ra, hogy a lehető legjobban ki tudja használni az Azure Cosmos DB által kínált lehetőségeket – egy felügyelt, nem relációs adatbázis-szolgáltatást versenyképes teljesítménnyel, öt-kilences rendelkezésre állással, egy fajta erőforrás-szabályozással és egyebekkel. Ez a cikk bemutatja, hogyan frissítheti meglévő Java-alkalmazását, amely egy régebbi Azure Cosmos DB Java SDK-t használ az újabb Azure Cosmos DB Java SDK 4.0 for API for NoSQL-re. Az Azure Cosmos DB Java SDK v4 a com.azure.cosmos csomagnak felel meg. A dokumentum utasításait akkor használhatja, ha az alkalmazást az alábbi Azure Cosmos DB Java SDK-k bármelyikéből migrálja:

  • Java SDK szinkronizálása 2.x.x
  • Async Java SDK 2.x.x
  • Java SDK 3.x.x

Azure Cosmos DB Java SDK-k és csomagleképezések

Az alábbi táblázat felsorolja a különböző Azure Cosmos DB Java SDK-kat, a csomag nevét és a kiadási információkat:

Java SDK Kiadás dátuma Csomagolt API-k Maven Jar Java-csomag neve API-referencia Release Notes (Kibocsátási megjegyzések) Kivonás dátuma
Async 2.x.x 2018. június Async(RxJava) com.microsoft.azure::azure-cosmosdb com.microsoft.azure.cosmosdb.rx API Kibocsátási megjegyzések 2024. augusztus 31., szombat
Szinkronizálás 2.x.x 2018. szeptember Sync com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API 2024. február 29., csütörtök
3.x.x 2019. július Async(Reactor)/Sync com.microsoft.azure::azure-cosmos com.azure.data.cosmos API - 2024. augusztus 31., szombat
4,0 2020. június Async(Reactor)/Sync com.azure::azure-cosmos com.azure.cosmos API - -

SDK-szintű implementáció változásai

A különböző SDK-k közötti főbb megvalósítási különbségek a következők:

Az RxJava helyére az Azure Cosmos DB Java SDK 3.x.x és 4.0-s verziói kerülnek

Ha nem ismeri az aszinkron programozást vagy a reaktív programozást, tekintse meg a Reactor mintaútmutatóját az aszinkron programozás és a Project Reactor bemutatásához. Ez az útmutató akkor lehet hasznos, ha korábban az Azure Cosmos DB Sync Java SDK 2.x.x vagy az Azure Cosmos DB Java SDK 3.x.x Sync API-t használta.

Ha az Azure Cosmos DB Async Java SDK 2.x.x-et használja, és a 4.0 SDK-ra való migrálást tervezi, tekintse meg a Reactor vs RxJava útmutatót az RxJava-kód Reactor használatára való konvertálásával kapcsolatban.

Az Azure Cosmos DB Java SDK v4 közvetlen kapcsolati móddal rendelkezik mind az Async, mind a Sync API-kban

Ha az Azure Cosmos DB Sync Java SDK 2.x.x-et használja, vegye figyelembe, hogy a TCP-n alapuló közvetlen kapcsolati mód (a HTTP helyett) az Azure Cosmos DB Java SDK 4.0-s verziójában van implementálva az Async és a Sync API-k esetében is.

API-szintű változások

Az azure Cosmos DB Java SDK 4.x.x api-szintű változásai a korábbi SDK-khoz képest (Java SDK 3.x.x, Async Java SDK 2.x.x és Sync Java SDK 2.x.x):

Azure Cosmos DB Java SDK naming conventions

  • Az Azure Cosmos DB Java SDK 3.x.x és 4.0 az ügyfélerőforrásokat a következőképpen tekinti Cosmos<resourceName>. Például, CosmosClient, CosmosDatabase. CosmosContainer Míg a 2.x.x verzióban az Azure Cosmos DB Java SDK-k nem rendelkeznek egységes elnevezési sémával.

  • Az Azure Cosmos DB Java SDK 3.x.x és 4.0 szinkronizálási és Async API-kat is kínál.

    • Java SDK 4.0 : Az összes osztály a Sync API-hoz tartozik, kivéve, ha az osztály neve hozzá van fűzve Async utána Cosmos.

    • Java SDK 3.x.x: Az összes osztály az Async API-hoz tartozik, kivéve, ha az osztály neve hozzá van fűzve Async utána Cosmos.

    • Aszinkron Java SDK 2.x.x: Az osztálynevek hasonlóak a Sync Java SDK 2.x.x-hez, de a név az Asynctel kezdődik.

Hierarchikus API-struktúra

Az Azure Cosmos DB Java SDK 4.0-s és 3.x.x-es verziójában hierarchikus API-struktúra jelenik meg, amely beágyazott módon rendszerezi az ügyfeleket, az adatbázisokat és a tárolókat, ahogyan az a következő 4.0 SDK-kódrészletben látható:

CosmosContainer container = client.getDatabase("MyDatabaseName").getContainer("MyContainerName");

Az Azure Cosmos DB Java SDK 2.x.x verziójában az erőforrásokon és dokumentumokon végzett összes művelet az ügyfélpéldányon keresztül történik.

Dokumentumok képviselete

Az Azure Cosmos DB Java SDK 4.0-s egyéni POJO-k, és JsonNodes két lehetőség a dokumentumok olvasására és írására az Azure Cosmos DB-ből.

Az Azure Cosmos DB Java SDK 3.x.x.x verziójában az CosmosItemProperties objektumot a nyilvános API teszi elérhetővé, és dokumentumábrázolásként szolgál. Ez az osztály már nem érhető el nyilvánosan a 4.0-s verzióban.

Importálások

  • Az Azure Cosmos DB Java SDK 4.0-s csomagjai a következővel kezdődnek: com.azure.cosmos

  • Az Azure Cosmos DB Java SDK 3.x.x csomagjai a következővel kezdődnek: com.azure.data.cosmos

  • Az Azure Cosmos DB Java SDK 2.x.x Sync API-csomagok a következővel kezdődnek: com.microsoft.azure.documentdb

  • Az Azure Cosmos DB Java SDK 4.0 több osztályt helyez el egy beágyazott csomagban com.azure.cosmos.models. A csomagok némelyike a következőket tartalmazza:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • Az Async API analógjai az összes fenti csomaghoz
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... Stb.

Tartozékok

Az Azure Cosmos DB Java SDK 4.0 elérhetővé teszi a példánytagokat és set a metódusokatget. Például a CosmosContainer példány rendelkezik és container.setId() metódusokkal rendelkezikcontainer.getId().

Ez eltér az Azure Cosmos DB Java SDK 3.x.x-től, amely egy folyékony felületet tesz elérhetővé. Például egy CosmosSyncContainer példány container.id() túlterhelt az érték lekéréséhez vagy beállításához id .

Kódrészletek összehasonlítása

Erőforrások létrehozása

Az alábbi kódrészlet a 4.0, 3.x.x Async, 2.x.x Szinkronizálás és 2.x.x Async API-k közötti erőforrások létrehozásának különbségeit mutatja be:


// Create Async client.
// Building an async client is still a sync operation.
CosmosAsyncClient client = new CosmosClientBuilder()
        .endpoint("your.hostname")
        .key("yourmasterkey")
        .consistencyLevel(ConsistencyLevel.EVENTUAL)
        .buildAsyncClient();

// Create database with specified name
client.createDatabaseIfNotExists("YourDatabaseName")
        .flatMap(databaseResponse -> {
            testDatabaseAsync = client.getDatabase("YourDatabaseName");
            // Container properties - name and partition key
            CosmosContainerProperties containerProperties =
                    new CosmosContainerProperties("YourContainerName", "/id");

            // Provision manual throughput
            ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

            // Create container
            return database.createContainerIfNotExists(containerProperties, throughputProperties);
        }).flatMap(containerResponse -> {
    testContainerAsync = database.getContainer("YourContainerName");
    return Mono.empty();
}).subscribe();

Elemműveletek

A következő kódrészlet a 4.0, 3.x.x Async, 2.x.x Szinkronizálás és 2.x.x Async API-k közötti elemműveletek végrehajtásának különbségeit mutatja be:


// Container is created. Generate many docs to insert.
int number_of_docs = 50000;
ArrayList<JsonNode> docs = generateManyDocs(number_of_docs);

// Insert many docs into container...
Flux.fromIterable(docs)
        .flatMap(doc -> testContainerAsync.createItem(doc))
        .subscribe(); // ...Subscribing triggers stream execution.

Indexelés

Az alábbi kódrészlet a 4.0, 3.x.x Async, 2.x.x Szinkronizálás és 2.x.x Async API-k közötti indexelés létrehozásának különbségeit mutatja be:


CosmosContainerProperties containerProperties = new CosmosContainerProperties(containerName, "/lastName");

// Custom indexing policy
IndexingPolicy indexingPolicy = new IndexingPolicy();
indexingPolicy.setIndexingMode(IndexingMode.CONSISTENT);

// Included paths
List<IncludedPath> includedPaths = new ArrayList<>();
includedPaths.add(new IncludedPath("/*"));
indexingPolicy.setIncludedPaths(includedPaths);

// Excluded paths
List<ExcludedPath> excludedPaths = new ArrayList<>();
excludedPaths.add(new ExcludedPath("/name/*"));
indexingPolicy.setExcludedPaths(excludedPaths);

containerProperties.setIndexingPolicy(indexingPolicy);

ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);

database.createContainerIfNotExists(containerProperties, throughputProperties);
CosmosAsyncContainer containerIfNotExists = database.getContainer(containerName);

Tárolt eljárások

Az alábbi kódrészlet a tárolt eljárások létrehozásának különbségeit mutatja be a 4.0, a 3.x.x Async, a 2.x.x Sync és a 2.x.x Async API-k között:


logger.info("Creating stored procedure...\n");

String sprocId = "createMyDocument";

String sprocBody = "function createMyDocument() {\n" +
        "var documentToCreate = {\"id\":\"test_doc\"}\n" +
        "var context = getContext();\n" +
        "var collection = context.getCollection();\n" +
        "var accepted = collection.createDocument(collection.getSelfLink(), documentToCreate,\n" +
        "    function (err, documentCreated) {\n" +
        "if (err) throw new Error('Error' + err.message);\n" +
        "context.getResponse().setBody(documentCreated.id)\n" +
        "});\n" +
        "if (!accepted) return;\n" +
        "}";

CosmosStoredProcedureProperties storedProcedureDef = new CosmosStoredProcedureProperties(sprocId, sprocBody);
container.getScripts()
        .createStoredProcedure(storedProcedureDef,
                new CosmosStoredProcedureRequestOptions()).block();

// ...

logger.info(String.format("Executing stored procedure %s...\n\n", sprocId));

CosmosStoredProcedureRequestOptions options = new CosmosStoredProcedureRequestOptions();
options.setPartitionKey(new PartitionKey("test_doc"));

container.getScripts()
        .getStoredProcedure(sprocId)
        .execute(null, options)
        .flatMap(executeResponse -> {
            logger.info(String.format("Stored procedure %s returned %s (HTTP %d), at cost %.3f RU.\n",
                    sprocId,
                    executeResponse.getResponseAsString(),
                    executeResponse.getStatusCode(),
                    executeResponse.getRequestCharge()));
            return Mono.empty();
        }).block();

Csatorna módosítása

Az alábbi kódrészlet a változáscsatorna-műveletek 4.0 és 3.x.x Async API-k közötti végrehajtásának különbségeit mutatja be:


ChangeFeedProcessor changeFeedProcessorInstance =
        new ChangeFeedProcessorBuilder()
                .hostName(hostName)
                .feedContainer(feedContainer)
                .leaseContainer(leaseContainer)
                .handleChanges((List<JsonNode> docs) -> {
                    logger.info("--->setHandleChanges() START");

                    for (JsonNode document : docs) {
                        try {
                            //Change Feed hands the document to you in the form of a JsonNode
                            //As a developer you have two options for handling the JsonNode document provided to you by Change Feed
                            //One option is to operate on the document in the form of a JsonNode, as shown below. This is great
                            //especially if you do not have a single uniform data model for all documents.
                            logger.info("---->DOCUMENT RECEIVED: " + OBJECT_MAPPER.writerWithDefaultPrettyPrinter()
                                    .writeValueAsString(document));

                            //You can also transform the JsonNode to a POJO having the same structure as the JsonNode,
                            //as shown below. Then you can operate on the POJO.
                            CustomPOJO pojo_doc = OBJECT_MAPPER.treeToValue(document, CustomPOJO.class);
                            logger.info("----=>id: " + pojo_doc.getId());

                        } catch (JsonProcessingException e) {
                            e.printStackTrace();
                        }
                    }
                    logger.info("--->handleChanges() END");

                })
                .buildChangeFeedProcessor();

// ...

changeFeedProcessorInstance.start()
        .subscribeOn(Schedulers.elastic())
        .subscribe();

Tárolószintű élettartam (TTL)

Az alábbi kódrészlet a tárolóban lévő adatok élettartamának 4.0, 3.x.x Async, 2.x.x Szinkronizálás és 2.x.x Async API-k közötti élettartamának különbségeit mutatja be:


CosmosAsyncContainer container;

// Create a new container with TTL enabled with default expiration value
CosmosContainerProperties containerProperties = new CosmosContainerProperties("myContainer", "/myPartitionKey");
containerProperties.setDefaultTimeToLiveInSeconds(90 * 60 * 60 * 24);
ThroughputProperties throughputProperties = ThroughputProperties.createManualThroughput(400);
database.createContainerIfNotExists(containerProperties, throughputProperties).block();
container = database.getContainer("myContainer");

Elemszintű élettartam(TTL)

Az alábbi kódrészlet a 4.0, 3.x.x aszinkron, 2.x.x szinkronizálási és 2.x.x aszinkron API-k közötti élettartam-létrehozási idő különbségeit mutatja be:


// Include a property that serializes to "ttl" in JSON
class SalesOrder
{
    private String id;
    private String customerId;
    private Integer ttl;

    public SalesOrder(String id, String customerId, Integer ttl) {
        this.id = id;
        this.customerId = customerId;
        this.ttl = ttl;
    }

    public String getId() {return this.id;}
    public void setId(String new_id) {this.id = new_id;}
    public String getCustomerId() {return this.customerId;}
    public void setCustomerId(String new_cid) {this.customerId = new_cid;}
    public Integer getTtl() {return this.ttl;}
    public void setTtl(Integer new_ttl) {this.ttl = new_ttl;}

    //...
}



// Set the value to the expiration in seconds
SalesOrder salesOrder = new SalesOrder(
        "SO05",
        "CO18009186470",
        60 * 60 * 24 * 30  // Expire sales orders in 30 days
);

Következő lépések