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

A KÖVETKEZŐKRE VONATKOZIK: SQL API

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ényével kapcsolatos tippeket é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ő legjobbat hozhassa ki az Azure Cosmos DB által kínált lehetőségek közül – egy felügyelt, nem relációs adatbázis-szolgáltatás versenyképes teljesítménnyel, öt-kilences rendelkezésre állással, egy fajta erőforrás-irányítással és egyebekkel. Ez a cikk azt ismerteti, hogyan frissítheti egy régebbi Azure Cosmos DB Java SDK-t használó meglévő Java-alkalmazását az újabb Azure Cosmos DB Java SDK 4.0 for Core (SQL) API-ra. Az Azure Cosmos DB Java SDK v4 megfelel a com.azure.cosmos csomagnak. Ha az alkalmazást az alábbi Azure Cosmos DB Java SDK-k bármelyikéből migrálja, a jelen dokumentumban található utasításokat használhatja:

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

Az Azure Cosmos DB Java SDK és csomagleképezései

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 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.
Sync 2.x.x 2018. szeptember Sync com.microsoft.azure::azure-documentdb com.microsoft.azure.cosmosdb API Kibocsátási megjegyzések 2024. február 29.
3.x.x 2019. július Async(Reactor)/Sync com.microsoft.azure::azure-cosmos com.azure.data.cosmos API - 2024. augusztus 31.
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-t az Azure Cosmos DB Java SDK 3.x.x és 4.0 verzióiban a reactor váltja fel

Ha nem ismeri az aszinkron programozást vagy a reaktív programozást, tekintse meg a Reactor mintaútmutatóját , amely bemutatja az aszinkron programozást és a Project Reactort. 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-s SDK-ra való migrálást tervezi, tekintse meg a Reactor és az RxJava útmutatót az RxJava-kód Reactor használatára való konvertálásához.

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

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ásai

Az alábbiakban az Azure Cosmos DB Java SDK 4.x.x API-szintű változásait tekintjük át 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 sync é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álynév hozzá van fűzve AsyncCosmosutána.

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

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

Hierarchikus API-struktúra

Az Azure Cosmos DB Java SDK 4.0-s és 3.x.x-es verziójában egy hierarchikus API-struktúra jelenik meg, amely az ügyfeleket, adatbázisokat és tárolókat beágyazott módon rendszerezi, ahogyan az a következő 4.0-s 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 ábrázolás

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 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.

Behozatal

  • Az Azure Cosmos DB Java SDK 4.0-csomagok 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. Néhány ilyen csomag:

    • CosmosContainerResponse
    • CosmosDatabaseResponse
    • CosmosItemResponse
    • Az Async API analógjai a fenti csomagok mindegyikéhez
    • CosmosContainerProperties
    • FeedOptions
    • PartitionKey
    • IndexingPolicy
    • IndexingMode ... Stb.

Tartozékok

Az Azure Cosmos DB Java SDK 4.0 elérhetővé teszi és set metódusokkal éri el a példánytagokatget. 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 verziójától, amely egy fluent felületet tesz elérhetővé. Egy példány container.id() például CosmosSyncContainer túlterhelt az érték lekéréséhez vagy beállításáhozid.

Kódrészletek összehasonlítása

Az erőforrások létrehozása

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 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

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 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

A következő kódrészlet bemutatja a tárolt eljárások létrehozásának különbségeit a 4.0, 3.x.x Async, 2.x.x Sync és 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 bemutatja a változáscsatorna-műveletek végrehajtásának különbségeit a 4.0 és a 3.x.x Async API-k között:


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 bemutatja, hogy miben különbözik a tárolóban lévő adatok élettartamának a 4.0, 3.x.x Async, 2.x.x Sync és 2.x.x Async API-k közötti élettartamának létrehozása:


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 Async, 2.x.x Sync és 2.x.x Async API-k közötti élettartam-létrehozási időt 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