Megosztás a következőn keresztül:

Rövid útmutató: Azure Cosmos DB ügyfélkönyvtár az Apache Cassandra számára Node.js

  • A következőre érvényes:: ✅ Apache Cassanda

Ismerkedés az Apache Cassandra Azure Cosmos DB ügyfélkódtárával, amellyel Node.js strukturálatlan adatokat tárolhat, kezelhet és kérdezhet le. Kövesse az útmutató lépéseit egy új fiók létrehozásához, egy Node.js ügyfélkódtár telepítéséhez, a fiókhoz való csatlakozáshoz, a gyakori műveletek végrehajtásához és a végső mintaadatok lekérdezéséhez.

API-referenciadokumentáció Kódtár forráskódcsomagja |

Előfeltételek

  • Azure-előfizetés

    • Ha nincs Azure-előfizetésed, hozz létre egy ingyenes fiókot mielőtt elkezdenéd.

  • Az Azure CLI legújabb verziója az Azure Cloud Shellben.

    • Ha inkább helyi cli-referenciaparancsokat szeretne futtatni, jelentkezzen be az Azure CLI-be a az login parancs használatával.
  • Node.js 22 vagy újabb

Előkészítés

Először állítsa be az útmutató fiók- és fejlesztési környezetét. Ez a szakasz végigvezeti a fiók létrehozásának, a hitelesítő adatok beszerzésének, majd a fejlesztési környezet előkészítésének folyamatán.

Fiók létrehozása

Először hozzon létre egy API-t apache Cassandra-fiókhoz. A fiók létrehozása után hozza létre a kulcsteret és a táblaerőforrásokat.

  1. Ha még nincs célerőforráscsoportja, a az group create paranccsal hozzon létre egy új erőforráscsoportot az előfizetésben.

    az group create \
    --name "<resource-group-name>" \
    --location "<location>"

  2. az cosmosdb create A paranccsal hozzon létre egy új Azure Cosmos DB-fiókot az Apache Cassandra-fiókhoz alapértelmezett beállításokkal.

    az cosmosdb create \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --locations "regionName=<location>" \
    --capabilities "EnableCassandra"

  3. Hozzon létre egy új kulcsteret az cosmosdb cassandra keyspace create használatával, amit cosmicworks nevére elnevezett.

    az cosmosdb cassandra keyspace create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --name "cosmicworks"

  4. Hozzon létre egy új JSON-objektumot, amely egy többsoros Bash-paranccsal ábrázolja a sémát. Ezután a az cosmosdb cassandra table create paranccsal hozzon létre egy új táblát.products

    schemaJson=$(cat <<EOF
{
  "columns": [
    {
      "name": "id",
      "type": "text"
    },
    {
      "name": "name",
      "type": "text"
    },
    {
      "name": "category",
      "type": "text"
    },
    {
      "name": "quantity",
      "type": "int"
    },
    {
      "name": "price",
      "type": "decimal"
    },
    {
      "name": "clearance",
      "type": "boolean"
    }
  ],
  "partitionKeys": [
    {
      "name": "id"
    }
  ]
}
EOF
)

    az cosmosdb cassandra table create \
    --resource-group "<resource-group-name>" \
    --account-name "<account-name>" \
    --keyspace-name "cosmicworks" \
    --name "product" \
    --schema "$schemaJson"

Hitelesítő adatok lekérése

Most szerezze be az ügyfélkódtár jelszavát, amellyel kapcsolatot hozhat létre a nemrég létrehozott fiókkal.

  1. A fiók kapcsolattartási pontjának és felhasználónevének lekérésére használható az cosmosdb show .

    az cosmosdb show \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --query "{username:name,contactPoint:documentEndpoint}"

  2. Jegyezze le az contactPoint és username tulajdonságok értékét az előző parancsok kimenetéből. Ezeknek a tulajdonságoknak az értékei: a kapcsolattartási pont és a felhasználónév, amelyeket a könyvtárral való fiók-csatlakozáshoz használ az útmutató következő részeiben.

  3. A fiók az cosmosdb keys list lekéréséhez használható.

    az cosmosdb keys list \
    --resource-group "<resource-group-name>" \
    --name "<account-name>" \
    --type "keys"

  4. Jegyezze fel a primaryMasterKey tulajdonság értékét az előző parancsok kimenetéből. Ennek a tulajdonságnak az értéke az jelszó, amit az útmutató későbbi részében használni fogsz a könyvtár segítségével a fiókhoz való csatlakozáshoz.

Fejlesztési környezet előkészítése

Ezután konfigurálja a fejlesztési környezetet egy új projekttel és az ügyfélkódtárral. Ez a lépés az utolsó szükséges előfeltétel, mielőtt továbblépne az útmutató többi részére.

  1. Kezdje egy üres mappában.

  2. Új modul inicializálása.

    npm init es6 --yes

  3. Telepítse a csomagot a cassandra-driver Node Package Managerből (npm).

    npm install --save cassandra-driver

  4. Hozza létre a index.js fájlt.

  1. Kezdje egy üres mappában.

  2. Új modul inicializálása.

    npm init es6 --yes

  3. Telepítse a csomagot a typescript Node Package Managerből (npm).

    npm install --save-dev typescript

  4. Telepítse az tsx csomagot az npm-ből.

    npm install --save-dev tsx

  5. Telepítse az cassandra-driver csomagot az npm-ből.

    npm install --save cassandra-driver

  6. Inicializálja a TypeScript-projektet a fordítóval (tsc).

    npx tsc --init --target es2017 --module es2022 --moduleResolution nodenext

  7. Hozza létre a index.ts fájlt.

Objektummodell

Leírás
Client Egy specifikus klaszterkapcsolatot képvisel.
Mapper A lekérdezések futtatásához használt Cassandra Query Language (CQL) ügyfél

Példakódok

Ügyfél hitelesítése

Első lépésként hitelesíti az ügyfelet az útmutatóban korábban összegyűjtött hitelesítő adatokkal.

  1. Nyissa meg a index.js fájlt az integrált fejlesztési környezetben (IDE).

  2. Importálja a következő típusokat a cassandra-driver modulból:

    • cassandra
    • cassandra.Client
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import cassandra from 'cassandra-driver';

const { Client } = cassandra;
const { Mapper } = cassandra.mapping;
const { PlainTextAuthProvider } = cassandra.auth;

  3. Sztringállandó változók létrehozása az útmutatóban korábban gyűjtött hitelesítő adatokhoz. Nevezze el a változókat username, passwordés contactPoint.

    const username = '<username>';
const password = '<password>';
const contactPoint = '<contact-point>';

  4. Hozzon létre egy másik karakterlánc változót ahhoz a régióhoz, ahol létrehozta az Azure Cosmos DB fiókot az Apache Cassandra számára. Nevezze el ezt a változót region.

    const region = '<azure-region>';

  5. Hozzon létre egy új PlainTextAuthProvider objektumot az előző lépésekben megadott hitelesítő adatokkal.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Hozzon létre egy Client objektumot az előző lépésekben létrehozott hitelesítő és konfigurációs változók használatával.

    let client = new Client({
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: {
        secureProtocol: 'TLSv1_2_method'
    },
});

  7. Aszinkron módon csatlakozzon a fürthöz.

    await client.connect();

  8. Hozzon létre egy új leképezőt, amely a cosmicworks kulcs-teret és a product táblát célozza meg. Nevezze meg a leképezőt Product.

    const mapper = new Mapper(client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  9. Hozzon létre egy leképezőpéldányt a forModel függvény és a Product leképező neve használatával.

    const productMapper = mapper.forModel('Product');

  1. Nyissa meg a index.ts fájlt az integrált fejlesztési környezetben (IDE).

  2. Importálja a következő típusokat a cassandra-driver modulból:

    • cassandra.auth
    • cassandra.mapping
    • cassandra.types
    • cassandra.Client
    • cassandra.ClientOptions
    • cassandra.mapping.Mapper
    • cassandra.auth.PlainTextAuthProvider
    import { auth, mapping, types, Client, ClientOptions } from 'cassandra-driver';

const { Mapper } = mapping;
const { PlainTextAuthProvider } = auth;

  3. Sztringállandó változók létrehozása az útmutatóban korábban gyűjtött hitelesítő adatokhoz. Nevezze el a változókat username, passwordés contactPoint.

    const username: string = '<username>';
const password: string = '<password>';
const contactPoint: string = '<contact-point>';

  4. Hozzon létre egy másik karakterlánc változót ahhoz a régióhoz, ahol létrehozta az Azure Cosmos DB fiókot az Apache Cassandra számára. Nevezze el ezt a változót region.

    const region: string = '<azure-region>';

  5. Hozzon létre egy új PlainTextAuthProvider objektumot az előző lépésekben megadott hitelesítő adatokkal.

    let authProvider = new PlainTextAuthProvider(
    username,
    password
);

  6. Hozzon létre egy névtelen objektumot olyan beállításokkal, amelyek biztosítják, hogy a transport layer security (TLS) 1.2 protokollt használja.

    let sslOptions = {
    secureProtocol: 'TLSv1_2_method'
};

  7. Hozzon létre egy ClientOptions objektumot az előző lépésekben létrehozott hitelesítő és konfigurációs változók használatával.

    let clientOptions: ClientOptions = {
    contactPoints: [`${contactPoint}:10350`],
    authProvider: authProvider,
    localDataCenter: region,
    sslOptions: sslOptions
};

  8. Hozzon létre egy objektumot Client a clientOptions konstruktor változójának használatával.

    let client = new Client(clientOptions);

  9. Aszinkron módon csatlakozzon a fürthöz.

    await client.connect();

  10. Hozzon létre egy új leképezőt, amely a cosmicworks kulcs-teret és a product táblát célozza meg. Nevezze meg a leképezőt Product.

    const mapper = new Mapper( client, {
    models: {
        'Product': {
            tables: ['product'],
            keyspace: 'cosmicworks'
        }
    }
});

  11. Hozzon létre egy leképezőpéldányt a forModel függvény és a Product leképező neve használatával.

    const productMapper = mapper.forModel('Product');

Figyelmeztetés

Ebben az útmutatóban le van tiltva a teljes átviteli rétegbiztonság (TLS) ellenőrzése a hitelesítés egyszerűsítése érdekében. Éles telepítéseknél teljesen engedélyezze az érvényesítést.

Adatok frissítése vagy beszúrása

Következő lépésként új adatokat kell beszúrni egy táblába. Az Upserting biztosítja az adatok megfelelő létrehozását vagy cseréjét attól függően, hogy ugyanazok az adatok már léteznek-e a táblában.

  1. Hozzon létre egy új objektumot egy nevű változóban product.

    const product = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    name: 'Yamba Surfboard',
    category: 'gear-surf-surfboards',
    quantity: 12,
    price: 850.00,
    clearance: false
};

  2. Hívja meg aszinkron módon az insert függvényt, átadva az előző lépésben létrehozott product változót.

    await productMapper.insert(product);

  1. Adjon meg egy új, az útmutatóban korábban létrehozott táblának megfelelő mezőkkel elnevezett Product felületet.

    Típus
    Id string
    Name string
    Category string
    Quantity int
    Price decimal
    Clearance bool 
    interface Product {
    id: string;
    name: string;
    category: string;
    quantity: number;
    price: number;
    clearance: boolean;
}

    Jótanács

    A Node.jstípus létrehozható egy másik fájlban, vagy elhelyezhető a meglévő fájl végén.

  2. Hozzon létre egy új típusú Productobjektumot. Tárolja az objektumot egy névvel ellátott productváltozóban.

    const product: Product = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
    name: 'Yamba Surfboard',
    category: 'gear-surf-surfboards',
    quantity: 12,
    price: 850.00,
    clearance: false
};

  3. Hívja meg aszinkron módon az insert függvényt, átadva az előző lépésben létrehozott product változót.

    await productMapper.insert(product);

Adatok beolvasása

Ezután olvassa be azokat az adatokat, amelyeket korábban a táblázatba illesztett be.

  1. Hozzon létre egy névtelen objektumot .filter Ebben az objektumban adjon meg egy olyan tulajdonságot id , amelynek neve ugyanaz, mint a jelen útmutatóban korábban létrehozott termék.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. Hívja meg a get változóban áthaladó leképező függvényét filter . Tárolja az eredményt egy névvel ellátott matchedProductváltozóban.

    let matchedProduct = await productMapper.get(filter);

  1. Hozzon létre egy névtelen objektumot .filter Ebben az objektumban adjon meg egy olyan tulajdonságot id , amelynek neve ugyanaz, mint a jelen útmutatóban korábban létrehozott termék.

    const filter = {
    id: 'aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb'
};

  2. Hívja meg a get változóban áthaladó leképező függvényét filter . Az eredményt egy matchedProducttípusú Product nevű változóban tárolja.

    let matchedProduct: Product = await productMapper.get(filter);

Adatok lekérdezése

Végül egy lekérdezéssel megkeresheti a táblában egy adott szűrőnek megfelelő összes adatot.

  1. Hozzon létre egy új karakterlánc változót query, amely CQL-lekérdezést tartalmaz, és megegyezik az azonos category mezővel rendelkező elemekkel.

    const query = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. Hozzon létre egy névtelen objektumot .params Ebben az objektumban adjon meg egy olyan tulajdonságot category , amelynek neve ugyanaz, mint a jelen útmutatóban korábban létrehozott termék.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. Aszinkron módon hívja meg a execute függvényt, és argumentumként adja át a query és params változókat. Az eredmény tulajdonságát rows egy névvel ellátott matchedProductsváltozóként tárolja.

    let { rows: matchedProducts } = await client.execute(query, params);

  4. Iterálja a lekérdezés eredményeit a foreach metódus meghívásával a termékek tömbjén.

    matchedProducts.forEach(product => {
    // Do something here with each result
});

  1. Hozzon létre egy új karakterlánc változót query, amely CQL-lekérdezést tartalmaz, és megegyezik az azonos category mezővel rendelkező elemekkel.

    const query: string = `
SELECT
    *
FROM
    cosmicworks.product
WHERE
    category = :category
ALLOW FILTERING
`;

  2. Hozzon létre egy névtelen objektumot .params Ebben az objektumban adjon meg egy olyan tulajdonságot category , amelynek neve ugyanaz, mint a jelen útmutatóban korábban létrehozott termék.

    const params = {
    category: 'gear-surf-surfboards'
};

  3. Aszinkron módon hívja meg a execute függvényt, és argumentumként adja át a query és params változókat. Az eredményt egy resulttípusú types.ResultSet nevű változóban tárolja.

    let result: types.ResultSet = await client.execute(query, params);

  4. Az eredmény tulajdonságát rows egy típus matchedProductsnevű Product[] változóként tárolja.

    let matchedProducts: Product[] = result.rows;

  5. Iterálja a lekérdezés eredményeit a foreach metódus meghívásával a termékek tömbjén.

    matchedProducts.forEach((product: Product) => {
    // Do something here with each result
});

A kód futtatása

Futtassa az újonnan létrehozott alkalmazást egy terminál használatával az alkalmazáskönyvtárban.

node index.js

npx tsx index.ts

Erőforrások tisztítása

Ha már nincs szüksége a fiókra, távolítsa el a fiókot az Azure-előfizetésből az erőforrás törlésével .

az cosmosdb delete \
    --resource-group "<resource-group-name>" \
    --name "<account-name>"

Következő lépés

Az Apache Cassandra-hoz készült Azure Cosmos DB áttekintése

  • Last updated on