Zestaw SDK Node.js usługi Azure Cosmos DB dla interfejsu API for NoSQL: informacje o wersji i zasoby

  • Artykuł

DOTYCZY: NoSQL

Zasób Link
Pobierz zestaw SDK @azure/cosmos
Dokumentacja interfejsu API Dokumentacja referencyjna zestawu SDK języka JavaScript
Instrukcje dotyczące instalacji zestawu SDK npm install @azure/cosmos
Współtworzenie zestawu SDK Przewodnik współtworzenia dla repozytorium azure-sdk-for-js
Przykłady przykłady kodu Node.js
Samouczek wprowadzający Wprowadzenie do zestawu SDK języka JavaScript
Samouczek dotyczący aplikacji internetowej Tworzenie aplikacji internetowej Node.js przy użyciu usługi Azure Cosmos DB
Bieżące obsługiwane platformy Node.js Wersje LTS Node.js

Informacje o wersji

Historia wersji jest przechowywana w repozytorium azure-sdk-for-js, aby uzyskać szczegółową listę wydań, zobacz plik dziennika zmian.

Przewodnik migracji zmian powodujących niezgodność

Jeśli korzystasz ze starszej wersji zestawu SDK, zaleca się przeprowadzenie migracji do wersji 3.0. W tej sekcji szczegółowo poznać ulepszenia wprowadzone w tej wersji oraz poprawki błędów wprowadzone w wersji 3.0.

Ulepszone opcje konstruktora klienta

Opcje konstruktora zostały uproszczone:

  • Nazwa klucza masterKey została zmieniona i przeniesiona na najwyższy poziom
  • Właściwości wcześniej w obszarze options.auth zostały przeniesione do najwyższego poziomu
// 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"
})

Uproszczony interfejs API iteratora zapytań

W wersji 2 istnieje wiele różnych sposobów iteracji lub pobierania wyników z zapytania. Podjęto próbę uproszczenia interfejsu API w wersji 3 i usunięcia podobnych lub zduplikowanych interfejsów API:

  • Usuń iterator.next() i iterator.current(). Użyj metody fetchNext(), aby uzyskać strony wyników.
  • Usuń iterator.forEach(). Zamiast tego użyj iteratorów asynchronicznych.
  • zmieniono nazwę iterator.executeNext() na iterator.fetchNext()
  • zmieniono nazwę iterator.toArray() na iterator.fetchAll()
  • Strony są teraz właściwymi obiektami odpowiedzi zamiast zwykłych obiektów JS
  • 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)
}

Stałe kontenery są teraz partycjonowane

Usługa Azure Cosmos DB obsługuje teraz klucze partycji we wszystkich kontenerach, w tym te, które zostały wcześniej utworzone jako stałe kontenery. Zestaw SDK w wersji 3 aktualizuje najnowszą wersję interfejsu API, która implementuje tę zmianę, ale nie powoduje to przerwania. Jeśli nie podasz klucza partycji dla operacji, domyślnie użyjemy klucza systemowego, który współdziała ze wszystkimi istniejącymi kontenerami i dokumentami.

Usunięto upsert dla procedur składowanych

Wcześniej operacja upsert była dozwolona dla kolekcji bez partycji, ale w przypadku aktualizacji wersji interfejsu API wszystkie kolekcje są partycjonowane, więc całkowicie je usunęliśmy.

Odczyty elementów nie będą zgłaszane na 404

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') }

Domyślne zapisy w wielu regionach

Zestaw SDK będzie teraz zapisywać w wielu regionach domyślnie, jeśli konfiguracja usługi Azure Cosmos DB go obsługuje. To było wcześniej zachowanie opt-in.

Prawidłowe obiekty błędów

Żądania, które zakończyły się niepowodzeniem, zgłaszają teraz prawidłowe błędy lub podklasy błędu. Wcześniej rzucali zwykłe obiekty JS.

Nowe funkcje

Żądania, które można anulować przez użytkownika

Przeniesienie do pobrania wewnętrznie umożliwia korzystanie z interfejsu API AbortController przeglądarki do obsługi operacji anulowania użytkownika. W przypadku operacji, w których potencjalnie trwa wiele żądań (takich jak zapytania obejmujące wiele partycji), wszystkie żądania operacji zostaną anulowane. Użytkownicy nowoczesnej przeglądarki będą już mieć abortController. Node.js użytkownicy będą musieli używać biblioteki Polyfill

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

Ustawianie przepływności w ramach operacji tworzenia bazy danych/kontenera

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

@azure/cosmos-sign

Generowanie tokenu nagłówka zostało podzielone na nową bibliotekę @azure/cosmos-sign. Każda osoba wywołująca interfejs API REST usługi Azure Cosmos DB bezpośrednio może użyć tego polecenia do podpisywania nagłówków przy użyciu tego samego kodu, który wywołujemy wewnątrz @azure/cosmoselementu .

Identyfikator UUID dla wygenerowanych identyfikatorów

Wersja 2 miała kod niestandardowy do generowania identyfikatorów elementów. Przeszliśmy do dobrze znanego i obsługiwanego identyfikatora biblioteki społeczności.

Parametry połączeń

Teraz można przekazać parametry połączenia skopiowaną z witryny 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()

Ulepszone środowisko przeglądarki

Chociaż można było użyć zestawu SDK w wersji 2 w przeglądarce, nie było to idealne środowisko. Aby polyfill kilka Node.js wbudowanych bibliotek i używać pakietu, takiego jak webpack lub Parcel. Zestaw SDK w wersji 3 sprawia, że środowisko gotowe do użycia jest znacznie lepsze dla użytkowników przeglądarki.

  • Zamień wewnętrzne żądania na pobieranie (#245)
  • Usuwanie użycia buforu (#330)
  • Usuwanie użycia węzła wbudowanego na rzecz uniwersalnych pakietów/interfejsów API (#328)
  • Przełącz się do węzła-abort-controller (#294)

Poprawki błędów

  • Naprawianie testów oferty odczytu i powrotu ofert (#224)
  • Poprawka enableEndpointDiscovery (#207)
  • Naprawianie brakujących jednostek RU w wynikach podzielonych na strony (#360)
  • Rozwiń typ parametru zapytania SQL (#346)
  • Dodawanie czasu wygaśnięcia do elementu ItemDefinition (#341)
  • Naprawianie metryk zapytań CP (#311)
  • Dodawanie identyfikatora activityId do elementu FeedResponse (#293)
  • Przełącz typ _ts z ciągu na liczbę (#252)(#295)
  • Naprawianie agregacji opłat za żądanie (#289)
  • Zezwalaj na puste klucze partycji ciągu (#277)
  • Dodawanie ciągu do typu zapytania powodującego konflikt (#237)
  • Dodawanie elementu uniqueKeyPolicy do kontenera (#234)

Systemy inżynieryjne

Nie zawsze najbardziej widoczne zmiany, ale pomagają naszemu zespołowi dostarczać lepszy kod, szybciej.

  • Używanie zestawienia dla kompilacji produkcyjnych (#104)
  • Aktualizacja do języka TypeScript 3.5 (#327)
  • Konwertuj na odwołania do projektu TS. Wyodrębnianie folderu testowego (#270)
  • Włączanie parametrów noUnusedLocals i noUnusedParameters (#275)
  • Azure Pipelines YAML for CI builds (#298)

Daty wydania i wycofania

Firma Microsoft udostępnia powiadomienie co najmniej 12 miesięcy przed wycofaniem zestawu SDK w celu złagodzenia przejścia na nowszą/obsługiwaną wersję. Nowe funkcje i funkcje i optymalizacje są dodawane tylko do bieżącego zestawu SDK, dlatego zaleca się, aby zawsze uaktualniać do najnowszej wersji zestawu SDK tak szybko, jak to możliwe. Aby uzyskać więcej informacji, zapoznaj się z zasadami pomoc techniczna firmy Microsoft dla zestawów SDK.

Wersja Data wydania Data wycofania
v3 28 czerwca 2019 r. ---
v2 24 września 2018 r. 24 września 2021 r.
v1 8 kwietnia 2015 r. 30 sierpnia 2020 r.

Często zadawane pytania

W jaki sposób będę otrzymywać powiadomienia o wycofywanym zestawie SDK?

Firma Microsoft wyśle powiadomienie na 12 miesięcy przed zakończeniem obsługi wycofywanego zestawu SDK, aby ułatwić bezproblemowe przejście do obsługiwanego zestawu SDK. Powiadomimy Cię za pośrednictwem różnych kanałów komunikacyjnych: witryny Azure Portal, aktualizacji platformy Azure i komunikacji bezpośredniej z przypisanymi administratorami usług.

Czy w ciągu tego 12-miesięcznego okresu mogę tworzyć aplikacje przy użyciu zestawu SDK Azure Cosmos DB?

Tak, w ciągu tego 12-miesięcznego okresu będziesz mieć możliwość tworzenia, wdrażania i modyfikowania aplikacji przy użyciu wycofywanego zestawu SDK Azure Cosmos DB. Zalecamy migrację do nowej obsługiwanej wersji zestawu SDK Azure Cosmos DB w ciągu tego 12-miesięcznego okresu zgodnie z potrzebami.

Co się stanie z aplikacjami korzystającymi z nieobsługiwanego zestawu SDK Azure Cosmos DB po jego wycofaniu?

Po dacie wycofania zespół Azure Cosmos DB nie będzie już opracowywał poprawek błędów, dodawał nowych funkcji ani zapewniał pomocy technicznej dla wycofanych wersji zestawu SDK. Jeśli nie chcesz przeprowadzać uaktualnienia, żądania wysyłane z wycofanej wersji zestawu SDK będą nadal obsługiwane przez usługę Azure Cosmos DB.

Które wersje zestawu SDK będą mieć najnowsze funkcje i aktualizacje?

Nowe funkcje i aktualizacje będą dodawane tylko do najnowszej wersji pomocniczej najnowszej obsługiwanej wersji zestawu SDK. Zalecamy używanie najnowszej wersji, aby korzystać z nowych funkcji, ulepszeń wydajności i poprawek błędów. Jeśli używasz starej, niewycofanej wersji zestawu SDK, żądania wysyłane do usługi Azure Cosmos DB będą nadal działać, ale nie będziesz mieć dostępu do żadnych nowych funkcji.

Co zrobić, jeśli nie mogę zaktualizować aplikacji przed datą progową?

Zalecamy przeprowadzenie uaktualnienia do najnowszej wersji zestawu SDK tak szybko, jak to możliwe. Gdy zestaw SDK zostanie oznaczony do wycofania, będziesz mieć 12 miesięcy na zaktualizowanie swojej aplikacji. Jeśli nie uda Ci się wykonać aktualizacji przed datą wycofania, żądania wysyłane z wycofanych wersji zestawu SDK nadal będą obsługiwane przez usługę Azure Cosmos DB, a zatem Twoje uruchomione aplikacje będą nadal działać. Jednak zespół Azure Cosmos DB nie będzie już opracowywał poprawek błędów, dodawał nowych funkcji ani zapewniał pomocy technicznej dla wycofanych wersji zestawu SDK.

Jeśli masz plan pomocy technicznej i potrzebujesz pomocy technicznej, skontaktuj się z nami, tworząc bilet pomocy technicznej.

Jak mogę zażądać dodania funkcji do zestawu SDK lub łącznika?

Nowe funkcje nie zawsze są natychmiast dodawane do każdego zestawu SDK lub łącznika. Jeśli funkcja nie jest obsługiwana, którą chcesz dodać, dodaj opinię do naszego forum społeczności.

Zobacz też

Aby dowiedzieć się więcej na temat usługi Azure Cosmos DB, zobacz stronę usługi Microsoft Azure Cosmos DB .