Az Azure Cosmos DB Node.js SDK for API for NoSQL: Kibocsátási megjegyzések és erőforrások

A KÖVETKEZŐRE VONATKOZIK: NoSQL

• .NET SDK v3
• .NET SDK v2
• .NET Core SDK v2
• .NET Change Feed SDK v2
• Node.js
• Java SDK v4
• Java SDK v2 szinkronizálása
• Async Java SDK v2
• Spring Data v2
• Spring Data v3
• Spring Data v5
• Python
• Ugrás
• REST
• REST erőforrás-szolgáltató
• SQL
• Tömeges végrehajtó – .NET v2
• Tömeges végrehajtó – Java

Erőforrás	Hivatkozás
SDK letöltése	@azure/cosmos
API-dokumentáció	JavaScript SDK-referenciadokumentáció
Az SDK telepítési útmutatója	npm install @azure/cosmos
Közreműködés az SDK-hoz	Útmutató az Azure-sdk-for-js adattárhoz
Példák	Node.js kódminták
Első lépések oktatóanyag	A JavaScript SDK használatának első lépései
Webalkalmazás-oktatóanyag	Node.js-webalkalmazás létrehozása az Azure Cosmos DB használatával
Jelenlegi támogatott Node.js platformok	A Node.js LTS-verziói

Kibocsátási megjegyzések

A kiadási előzmények az Azure-sdk-for-js adattárban maradnak fenn, a kiadások részletes listáját a changelog fájlban találja.

Migrálási útmutató a kompatibilitástörő változásokhoz

Ha az SDK egy régebbi verzióján dolgozik, javasoljuk, hogy migráljon a 3.0-s verzióra. Ez a szakasz részletesen ismerteti az ezzel a verzióval elérhető fejlesztéseket és a 3.0-s verzióban végrehajtott hibajavításokat.

Továbbfejlesztett ügyfélkonstruktor-beállítások

A konstruktor beállításai egyszerűbbek lettek:

• A masterKey átnevezve lett a kulcsra, és a legfelső szintre került
• A korábban a options.auth alatt lévő tulajdonságok a legfelső szintre kerültek

// v2
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    auth: {
        masterKey: "your-primary-key"
    }
})

// v3
const client = new CosmosClient({
    endpoint: "https://your-database.cosmos.azure.com",
    key: "your-primary-key"
})

Egyszerűsített lekérdezési iterátor API

A v2-ben számos különböző módon lehet iterálni vagy lekérni az eredményeket egy lekérdezésből. Megpróbáltuk egyszerűsíteni a v3 API-t, és eltávolítani a hasonló vagy duplikált API-kat:

• Távolítsa el az iterator.next() és az iterator.current() elemet. A fetchNext() használatával lekérheti az eredmények lapjait.
• Iterator.forEach() eltávolítása. Ehelyett használjon aszinkron iterátorokat.
• iterator.executeNext() átnevezve iterator.fetchNext()
• iterator.toArray() átnevezve iterator.fetchAll()
• A lapok mostantól megfelelő válaszobjektumok az egyszerű JS-objektumok helyett
• const container = client.database(dbId).container(containerId)

// v2
container.items.query('SELECT * from c').toArray()
container.items.query('SELECT * from c').executeNext()
container.items.query('SELECT * from c').forEach(({ body: item }) => { console.log(item.id) })

// v3
container.items.query('SELECT * from c').fetchAll()
container.items.query('SELECT * from c').fetchNext()
for await(const { result: item } in client.databases.readAll().getAsyncIterator()) {
    console.log(item.id)
}

A rögzített tárolók most particionáltak

Az Azure Cosmos DB szolgáltatás mostantól minden tárolón támogatja a partíciókulcsokat, beleértve a korábban rögzített tárolóként létrehozottakat is. A v3 SDK a módosítást megvalósító legújabb API-verzióra frissül, de nem törik meg. Ha nem ad meg partíciókulcsot a műveletekhez, alapértelmezés szerint egy olyan rendszerkulcsot adunk meg, amely az összes meglévő tárolóval és dokumentummal működik.

A tárolt eljárásokhoz eltávolított Upsert

Korábban a nem particionált gyűjtemények esetében engedélyezve volt a upsert, de az API verziófrissítésével minden gyűjtemény particionálásra került, így teljesen eltávolítottuk.

Az elemolvasások nem kerülnek a 404-be

const container = client.database(dbId).container(containerId)

// v2
try {
    container.items.read(id, undefined)
} catch (e) {
    if (e.code === 404) { console.log('item not found') }
}

// v3
const { result: item }  = container.items.read(id, undefined)
if (item === undefined) { console.log('item not found') }

Alapértelmezett többrégiós írások

Az SDK mostantól alapértelmezés szerint több régióba is ír, ha az Azure Cosmos DB-konfiguráció támogatja. Ez korábban a bejelentkezési viselkedés volt.

Megfelelő hibaobjektumok

A sikertelen kérések most már a megfelelő hibát vagy a hiba alosztályait adják vissza. Korábban egyszerű JS-objektumokat dobtak.

Új funkciók

Felhasználó által visszavonható kérelmek

A belső beolvasásra való áttérés lehetővé teszi, hogy a böngésző AbortController API-jának használatával támogassuk a felhasználó által lemondható műveleteket. Olyan műveletek esetén, amelyekben több kérés is lehetséges (például partícióközi lekérdezések), a művelet összes kérése megszakad. A modern böngésző felhasználói már rendelkeznek az AbortControllerrel. Node.js felhasználóknak polyfill-kódtárat kell használniuk

 const controller = new AbortController()
 const {result: item} = await items.query('SELECT * from c', { abortSignal: controller.signal});
 controller.abort()

Átviteli sebesség beállítása a db/tároló létrehozása művelet részeként

const { database }  = client.databases.create({ id: 'my-database', throughput: 10000 })
database.containers.create({ id: 'my-container', throughput: 10000 })

@azure/cosmos-sign

Az élőfej-jogkivonat létrehozása egy új kódtárra lett felosztva. @azure/cosmos-sign Bárki, aki közvetlenül az Azure Cosmos DB REST API-t hívja, használhatja fejlécek aláírására ugyanazzal a kóddal, amelyet belül @azure/cosmoshívunk.

UUID generált azonosítókhoz

A v2 egyéni kóddal rendelkezett az elemazonosítók létrehozásához. Váltottunk a jól ismert és karbantartott közösségi könyvtár uuid.

Kapcsolati sztringek

Mostantól át lehet adni egy kapcsolati sztring az Azure Portalról:

const client = new CosmosClient("AccountEndpoint=https://test-account.documents.azure.com:443/;AccountKey=c213asdasdefgdfgrtweaYPpgoeCsHbpRTHhxuMsTaw==;")
Add DISTINCT and LIMIT/OFFSET queries (#306)
 const { results } = await items.query('SELECT DISTINCT VALUE r.name FROM ROOT').fetchAll()
 const { results } = await items.query('SELECT * FROM root r OFFSET 1 LIMIT 2').fetchAll()

Továbbfejlesztett böngészőélmény

Bár a v2 SDK-t a böngészőben lehetett használni, nem volt ideális élmény. Több Node.js beépített kódtárat kellett polyfillre használnia, és olyan csomagcsomagolót kellett használnia, mint a webpack vagy a Parcel. A v3 SDK sokkal jobb élményt nyújt a böngésző felhasználói számára.

• Belső kérések cseréje beolvasásra (#245)
• Puffer használatának eltávolítása (#330)
• Csomópont beépített használatának eltávolítása az univerzális csomagok/API-k javára (#328)
• Váltás csomópont-megszakító vezérlőre (#294)

Hibajavítások

• Ajánlatolvasási és visszahozó ajánlattesztek javítása (#224)
• EnableEndpointDiscovery javítása (#207)
• Hiányzó kérelemegységek kijavítása lapszámozott eredményeken (#360)
• SQL-lekérdezés paramétertípusának kibontása (#346)
• Ttl hozzáadása az ItemDefinitionhez (#341)
• CP-lekérdezési metrikák javítása (#311)
• ActivityId hozzáadása a FeedResponse-hoz (#293)
• _ts típus váltása sztringről számra (#252)(#295)
• Kérelemdíj-összesítés javítása (#289)
• Üres sztringpartíciós kulcsok engedélyezése (#277)
• Sztring hozzáadása ütköző lekérdezéstípushoz (#237)
• UniqueKeyPolicy hozzáadása a tárolóhoz (#234)

Mérnöki rendszerek

Nem mindig a leglátottabb változások, de segítenek a csapatunknak jobb kódot szállítania, gyorsabban.

• Összesítő használata éles buildekhez (#104)
• Frissítés TypeScript 3.5-ös verzióra (#327)
• Konvertálás TS-projekthivatkozásokra. Tesztmappa kinyerés (#270)
• A noUnusedLocals és a noUnusedParameters engedélyezése (#275)
• Azure Pipelines YAML CI-buildekhez (#298)

Kiadási és kivonási dátumok

A Microsoft legalább 12 hónappal az SDK kivonása előtt értesítést küld, hogy zökkenőmentes legyen az áttérés egy újabb/támogatott verzióra. Az új funkciók, funkciók és optimalizálások csak az aktuális SDK-hoz lesznek hozzáadva, ezért javasoljuk, hogy a lehető leghamarabb frissítsen a legújabb SDK-verzióra. További részletekért olvassa el a Microsoft ügyfélszolgálata SDK-kra vonatkozó szabályzatot.

Verzió	Kiadás dátuma	Kivonás dátuma
v3	2019. június 28.	---
v2	2018. szeptember 24.	2021. szeptember 24.
v1	2015. április 08.	2020. augusztus 30.

GYIK

Hogyan fogok értesülni az SDK kivezetéséről?

A Microsoft értesítést küld 12 hónappal a kivezetett SDK támogatásának vége előtt, megkönnyítve a zökkenőmentes áttérést egy támogatott SDK-ra. Az értesítéseket különböző kommunikációs csatornákon továbbítjuk: az Azure Portalon, Azure-frissítés útján, valamint a hozzárendelt szolgáltatásadminisztrátorok közvetlen értesítésével.

Létrehozhatok alkalmazásokat egy hamarosan kivezetendő Azure Cosmos DB SDK-val ebben a 12 hónapos időszakban?

Igen, a 12 hónapos értesítési időszakban is lehet alkalmazásokat létrehozni, üzembe helyezni és módosítani a hamarosan kivezetendő Azure Cosmos DB SDK-val. Javasoljuk, hogy a 12 hónap folyamán lehetőleg mielőbb térjen át az Azure Cosmos DB SDK újabb, támogatott verziójára.

A kivezetési dátum után mi lesz a már nem támogatott Azure Cosmos DB SDK-t használó alkalmazásokkal?

A kivezetési dátum után az Azure Cosmos DB nem biztosít több hibajavítást, új funkciót és támogatást a kivezetett SDK-verziókhoz. Ha nem frissíti az SDK-t, az Azure Cosmos DB szolgáltatás továbbra is kiszolgálja az SDK kivezetett verziói által küldött kéréseket.

Melyik SDK-verziók kapják meg a legújabb funkciókat és frissítéseket?

Az új funkciók és frissítések csak a legújabb támogatott fő SDK-verzió legújabb alverziójában lesznek hozzáadva. Javasoljuk, hogy mindig használja a legújabb verziót, hogy hozzájusson az új funkciókhoz, teljesítménybeli fejlesztésekhez és hibajavításokhoz. Ha egy régebbi, még nem kivezetett SDK-verziót használ, akkor az Azure Cosmos DB felé küldött kérései továbbra is működni fognak, de nem lesz hozzáférése az új lehetőségekhez.

Mit tegyek, ha nem tudom frissíteni az alkalmazásomat egy megszűnési dátum előtt?

Javasoljuk, hogy mindig a lehető leghamarabb frissítsen a legújabb SDK-verzióra. Miután egy SDK kivezetendő megjelölést kap, 12 hónap áll rendelkezésre az alkalmazás frissítésére. Ha nem tudja elvégezni a frissítést a kivezetési dátumig, az Azure Cosmos DB szolgáltatás továbbra is kiszolgálja az SDK kivezetett verziói által küldött kéréseket, így a futó alkalmazások továbbra is működni fognak. Azonban az Azure Cosmos DB nem biztosít több hibajavítást, új funkciót és támogatást a kivezetett SDK-verziókhoz.

Ha rendelkezik támogatási csomaggal és műszaki támogatásra van szüksége, lépjen kapcsolatba velünk egy támogatási jegy beküldésével.

Hogyan kérhetem, hogy funkciók legyenek hozzáadva egy SDK-hoz vagy összekötőhöz?

Az új funkciók nem mindig jelennek meg azonnal minden SDK-hoz vagy összekötőhöz. Ha egy olyan funkció nem támogatott, amelyet hozzá szeretne adni, küldjön visszajelzést a közösségi fórumunkra.

Lásd még

Az Azure Cosmos DB-ről további információt a Microsoft Azure Cosmos DB szolgáltatásoldalán talál.