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

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 kódmintákNode.js
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.jsLTS-verziói

Kibocsátási megjegyzések

A kiadási előzmények az azure-sdk-for-js adattárban vannak fenntartva. 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át használja, javasoljuk, hogy migráljon a 3.0-s verzióra. Ez a szakasz az ezzel a verzióval elérhető fejlesztéseket és a 3.0-s verzióban végrehajtott hibajavításokat ismerteti.

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

A konstruktorok beállításai egyszerűbbek:

  • a masterKey nevet kulcsnak nevezték át, és a legfelső szintre helyezték át
  • A korábban az options.auth területen 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 lehetett iterálni vagy lekérni az eredményeket egy lekérdezésből. Megpróbáltuk leegyszerűsíteni a v3 API-t, és eltávolítani a hasonló vagy duplikált API-kat:

  • Távolítsa el az iterátor.next() és az iterátor.current() elemet. Az eredmények lapjainak lekéréséhez használja a fetchNext() parancsot.
  • Távolítsa el az iterator.forEach() elemet. 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 particionálása most már megtörtént

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, akkor alapértelmezés szerint egy olyan rendszerkulcsot adunk meg, amely az összes meglévő tárolóval és dokumentummal működik.

Upsert el lett távolítva a tárolt eljárásokhoz

Korábban a upsert engedélyezve volt a nem particionált gyűjteményekhez, de az API verziófrissítésével az összes gyűjtemény particioná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 azt. Ez korábban a bejelentkezési viselkedés volt.

Megfelelő hibaobjektumok

A sikertelen kérések most már a megfelelő hiba- vagy alosztályokat jelzik. Korábban egyszerű JS-objektumokat dobtak.

Új funkciók

Felhasználó által lemondható kérések

A belső beolvasásra való áttérés lehetővé teszi számunkra, hogy az AbortController API böngészővel támogassuk a felhasználó által lemondható műveleteket. Olyan műveletek esetén, amelyekben több kérelem is folyamatban van (például keresztpartíciós 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/container create 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

A fejléc-jogkivonat-létrehozás egy új kódtárra lett felosztva, a @azure/cosmos-sign. Bárki, aki közvetlenül meghívja az Azure Cosmos DB REST API-t, ezzel aláírhatja a fejléceket ugyanazzal a kóddal, amelyet a fájlban hívunk meg @azure/cosmos.

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 a Azure Portal:

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 lehetett használni a böngészőben, nem volt ideális élmény. Több beépített kódtárat kellett több Node.js polyfillbe töltenie, és használnia kellett egy csomagköteget, például a webpackot vagy a Parcelet. A v3 SDK sokkal jobb felhasználói élményt nyújt a dobozból.

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

Hibajavítások

  • Ajánlatolvasási és visszahozott ajánlattesztek javítása (#224)
  • EnableEndpointDiscovery (#207) javítása
  • Hiányzó kérelemegységek javítása lapszámozott eredményeken (#360)
  • SQL-lekérdezés paramétertípusának kibontása (#346)
  • Ttl hozzáadása az ItemDefinition elemhez (#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 az ütköző lekérdezés típusához (#237)
  • UniqueKeyPolicy hozzáadása a tárolóhoz (#234)

Mérnöki rendszerek

Nem mindig a leglátogatottabb változások, de segítenek a csapatnak jobb kódot, gyorsabb.

  • Kumulatív buildek használata (#104)
  • Frissítés TypeScript 3.5-ös verzióra (#327)
  • Konvertálás TS-projekthivatkozásokká. Tesztmappa kinyerés (#270)
  • NoUnusedLocals és noUnusedParameters engedélyezése (#275)
  • Azure Pipelines YAML CI-buildekhez (#298)

Kiadási & kivezetés dátumai

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. Új szolgáltatásokkal, funkciókkal és optimalizálásokkal csak az aktuális SDK bővül, ezért azt javasoljuk, hogy a mindig lehető leghamarabb frissítsen a legújabb SDK-verzióra. További részletekért olvassa el az SDK-k Microsoft ügyfélszolgálata szabályzatát.

Verzió Kiadás dátuma Kivonás dátuma
v3 2019. június 28. ---
v2 24, 2018. szeptember 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érhetek szolgáltatásokat egy SDK-hoz vagy összekötőhöz?

Az új funkciók nem minden SDK-hoz vagy összekötőhöz kerülnek azonnal. Ha van olyan funkció, amelyet nem szeretne hozzáadni, kérjük, adjon visszajelzést a közösségi fórumunkhoz.

Lásd még

További információ az Azure Cosmos DB-ről: Microsoft Azure Cosmos DB szolgáltatáslap.