INTEGRITY Dokumentace

Vytvoření API pro přístup k D1 pomocí proxy Workeru

V tomto tutoriálu se naučíte, jak vytvořit API, které umožní bezpečně spouštět dotazy vůči databázi D1.

To se hodí, pokud chcete přistupovat k databázi D1 mimo projekt Worker nebo Pages, přizpůsobit řízení přístupu nebo omezit, které tabulky lze dotazovat.

vestavěné REST API se nejlépe hodí pro administrativní použití jako globální Limit počtu požadavků Cloudflare API platí.

Chcete-li přistupovat k databázi D1 mimo projekt Worker, musíte pomocí Workeru vytvořit API. Vaše aplikace pak může s tímto API bezpečně komunikovat a spouštět dotazy D1.

Předpoklady

  1. Zaregistrujte si účet Cloudflare.
  2. Nainstalujte Node.js.
  3. Mějte existující databázi D1. Viz Úvodní tutoriál pro D1.

Správce verzí Node.js

Použijte správce verzí Node, jako je Volta nebo nvm abyste se vyhnuli problémům s oprávněními a měnili verze Node.js. Wrangler, o kterém se dále hovoří v tomto průvodci, vyžaduje verzi Node 16.17.0 nebo novější.

1. Vytvořte nový projekt

Vytvořte nový Worker, pomocí kterého vytvoříte a nasadíte své API.

  1. Vytvořte Worker s názvem d1-http spuštěním:

    npm create cloudflare@latest -- d1-http

    Při nastavení vyberte následující možnosti:

    • Pro S čím byste chtěli začít?, vyberte Hello World example.
    • Pro Jakou šablonu chcete použít?, vyberte Worker only.
    • Pro Jaký jazyk chcete použít?, vyberte TypeScript.
    • Pro Chcete používat git pro správu verzí?, vyberte Yes.
    • Pro Chcete nasadit svou aplikaci?, vyberte No (před nasazením provedeme ještě několik změn).
  2. Přejděte do adresáře nového projektu a začněte vyvíjet:

    cd d1-http

2. Nainstalujte Hono

V tomto tutoriálu použijete Hono, framework ve stylu Express.js, k sestavení API.

  1. Pro použití Hono v tomto projektu ho nainstalujte pomocí npm:

    npm i hono

3. Přidejte API_KEY

Pro autentizovaná volání API potřebujete klíč API. Aby byl klíč API v bezpečí, přidejte ho jako secret.

  1. Pro lokální vývoj vytvořte .dev.vars soubor v kořenovém adresáři d1-http.

  2. Do souboru přidejte svůj API klíč následujícím způsobem.

    .dev.vars
    API_KEY="YOUR_API_KEY"

    Nahraďte YOUR_API_KEY s platnou textovou hodnotou. Tuto hodnotu můžete také vygenerovat pomocí následujícího příkazu.

    openssl rand -base64 32

4. Inicializujte aplikaci

Pro inicializaci aplikace je třeba naimportovat potřebné balíčky, inicializovat novou aplikaci Hono a nakonfigurovat následující middleware:

  1. Nahraďte obsah src/index.ts soubor kódem níže.

    src/index.ts
    import { Hono } from "hono";
    import { bearerAuth } from "hono/bearer-auth";
    import { logger } from "hono/logger";
    import { prettyJSON } from "hono/pretty-json";
    
    type Bindings = {
    	API_KEY: string;
    };
    
    const app = new Hono<{ Bindings: Bindings }>();
    
    app.use("*", prettyJSON(), logger(), async (c, next) => {
    	const auth = bearerAuth({ token: c.env.API_KEY });
    	return auth(c, next);
    });

5. Přidejte koncové body API

  1. Přidejte následující úryvek kódu do svého src/index.ts.

    src/index.ts
    
    // Paste this code at the end of the src/index.ts file
    
    app.post("/api/all", async (c) => {
    	return c.text("/api/all endpoint");
    });
    
    app.post("/api/exec", async (c) => {
    	return c.text("/api/exec endpoint");
    });
    
    app.post("/api/batch", async (c) => {
    	return c.text("/api/batch endpoint");
    });
    
    export default app;

    Tím se přidají následující koncové body:

    • POST /api/all
    • POST /api/exec
    • POST /api/batch
  2. Vývojový server spustíte zadáním následujícího příkazu:

    npm run dev
  3. Pro lokální otestování API otevřete druhý terminál.

  4. Ve druhém terminálu spusťte níže uvedený příkaz cURL. Nahraďte YOUR_API_KEY s hodnotou, kterou jste nastavili v .dev.vars .

    curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/all" --data '{}'

    Měli byste získat následující výstup:

    /api/all endpoint
  5. Místní server zastavíte stisknutím x v prvním terminálu.

Aplikace Hono je nyní nastavena. Můžete otestovat další koncové body a v případě potřeby jich přidat více. API zatím nevrací žádné informace z vaší databáze. V dalších krocích vytvoříte databázi, přidáte její bindings a upravíte koncové body tak, aby komunikovaly s databází.

6. Vytvořte databázi

Pokud ještě nemáte databázi D1, můžete novou databázi vytvořit pomocí wrangler d1 create.

  1. V terminálu spusťte:

    npx wrangler d1 create d1-http-example

    Možná budete vyzváni k přihlášení do účtu Cloudflare. Po přihlášení příkaz vytvoří novou databázi D1. V terminálu byste měli vidět podobný výstup.

    ✅ Successfully created DB 'd1-http-example' in region EEUR
    Created your new D1 database.
    
    [[d1_databases]]
    binding = "DB" # i.e. available in your Worker on env.DB
    database_name = "d1-http-example"
    database_id = "1234567890"

Poznamenejte si zobrazené database_name a database_id. Toto použijete k odkazování na databázi vytvořením binding.

7. Přidejte vazbu

  1. Z vašeho d1-http složku, otevřete soubor Wrangler, konfigurační soubor nástroje Wrangler.

  2. Do souboru přidejte následující vazbu. Ujistěte se, že database_name a database_id jsou správné.

    {
      "d1_databases": [
        {
          "binding": "DB", // i.e. available in your Worker on env.DB
          "database_name": "d1-http-example",
          "database_id": "1234567890"
        }
      ]
    }
    [[d1_databases]]
    binding = "DB"
    database_name = "d1-http-example"
    database_id = "1234567890"
  3. Ve vašem src/index.ts soubor a aktualizujte Bindings typ přidáním DB: D1Database.

    type Bindings = {
    	DB: D1Database;
    	API_KEY: string;
    };

Nyní máte přístup k databázi v aplikaci Hono.

8. Vytvořte tabulku

Chcete-li vytvořit tabulku v nově vytvořené databázi:

  1. Vytvořte novou složku s názvem schemas uvnitř vašeho d1-http složka.

  2. Vytvořte nový soubor s názvem schema.sql, a do souboru vložte následující příkaz SQL.

    schema.sql
    DROP TABLE IF EXISTS posts;
    CREATE TABLE IF NOT EXISTS posts (
    	id integer PRIMARY KEY AUTOINCREMENT,
    	author text NOT NULL,
    	title text NOT NULL,
    	body text NOT NULL,
    	post_slug text NOT NULL
    );
    INSERT INTO posts (author, title, body, post_slug) VALUES ('Harshil', 'D1 HTTP API', 'Learn to create an API to query your D1 database.','d1-http-api');

    Kód odstraní jakoukoli tabulku s názvem posts pokud existuje, a poté vytvoří novou tabulku posts s polem id, author, title, body, a post_slug. Poté pomocí příkazu INSERT naplní tabulku daty.

  3. V terminálu spusťte následující příkaz, který tuto tabulku vytvoří:

    npx wrangler d1 execute d1-http-example --file=./schemas/schema.sql

Po úspěšném provedení bude do vaší databáze přidána nová tabulka.

9. Proveďte dotaz na databázi

Vaše aplikace má nyní přístup k databázi D1. V tomto kroku upravíte koncové body API tak, aby databázi dotazovaly a vracely výsledek.

  1. Ve vašem src/index.ts soubor a aktualizujte kód následovně.

    src/index.ts
    // Update the API routes
    
    /**
    * Executes the `stmt.run()` method.
    * https://developers.cloudflare.com/d1/worker-api/prepared-statements/#run
    */
    
    app.post('/api/all', async (c) => {
    		return c.text("/api/all endpoint");
    	try {
    		let { query, params } = await c.req.json();
    		let stmt = c.env.DB.prepare(query);
    		if (params) {
    			stmt = stmt.bind(params);
    		}
    
    		const result = await stmt.run();
    		return c.json(result);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });
    
    /**
    * Executes the `db.exec()` method.
    * https://developers.cloudflare.com/d1/worker-api/d1-database/#exec
    */
    
    app.post('/api/exec', async (c) => {
    		return c.text("/api/exec endpoint");
    	try {
    		let { query } = await c.req.json();
    		let result = await c.env.DB.exec(query);
    		return c.json(result);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });
    
    /**
    * Executes the `db.batch()` method.
    * https://developers.cloudflare.com/d1/worker-api/d1-database/#batch
    */
    
    app.post('/api/batch', async (c) => {
    		return c.text("/api/batch endpoint");
    	try {
    		let { batch } = await c.req.json();
    		let stmts = [];
    		for (let query of batch) {
    			let stmt = c.env.DB.prepare(query.query);
    			if (query.params) {
    				stmts.push(stmt.bind(query.params));
    			} else {
    				stmts.push(stmt);
    			}
    		}
    		const results = await c.env.DB.batch(stmts);
    		return c.json(results);
    	} catch (err) {
    		return c.json({ error: `Failed to run query: ${err}` }, 500);
    	}
    });
    ...

Ve výše uvedeném kódu jsou koncové body upraveny tak, aby přijímaly query a params. Tyto dotazy a parametry se předávají příslušným funkcím, které komunikují s databází.

10. Otestujte API

Nyní, když API umí dotazovat databázi, ho můžete otestovat lokálně.

  1. Vývojový server spustíte pomocí následujícího příkazu:

    npm run dev
  2. V novém okně terminálu spusťte následující příkazy cURL. Nezapomeňte nahradit YOUR_API_KEY se správnou hodnotou.

    /api/all
    curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/all" --data '{"query": "SELECT title FROM posts WHERE id=?", "params":1}'
    /api/batch
    curl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/batch" --data '{"batch": [ {"query": "SELECT title FROM posts WHERE id=?", "params":1},{"query": "SELECT id FROM posts"}]}'
    /api/exec
    curl -H "Authorization: Bearer YOUR_API_KEY" "localhost:8787/api/exec" --data '{"query": "INSERT INTO posts (author, title, body, post_slug) VALUES ('\''Harshil'\'', '\''D1 HTTP API'\'', '\''Learn to create an API to query your D1 database.'\'','\''d1-http-api'\'')" }'

Pokud je vše implementováno správně, výše uvedené příkazy by měly skončit úspěšným výstupem.

11. Nasaďte API

Nyní, když vše funguje podle očekávání, zbývá poslední krok, a to nasazení do sítě Cloudflare. K nasazení API použijete Wrangler.

  1. Pro použití API v produkci místo lokálního použití je třeba přidat tabulku do vzdálené (produkční) databáze. Pro přidání tabulky do produkční databáze spusťte následující příkaz:

    npx wrangler d1 execute d1-http-example --file=./schemas/schema.sql --remote

    Nyní byste měli vidět tabulku na Cloudflare dashboard > Storage & Databases > D1.

  2. Chcete-li nasadit aplikaci do sítě Cloudflare, spusťte následující příkaz:

    npx wrangler deploy
     ⛅️ wrangler 3.78.4 (update available 3.78.5)
    -------------------------------------------------------
    
    Total Upload: 53.00 KiB / gzip: 13.16 KiB
    Your worker has access to the following bindings:
    - D1 Databases:
      - DB: d1-http-example (DATABASE_ID)
    Uploaded d1-http (4.29 sec)
    Deployed d1-http triggers (5.57 sec)
      [DEPLOYED_APP_LINK]
    Current Version ID: [BINDING_ID]

    Po úspěšném nasazení získáte v terminálu odkaz na nasazenou aplikaci (DEPLOYED_APP_LINK). Poznamenejte si ho.

  3. Vygenerujte nový API klíč pro použití v produkčním prostředí.

    openssl rand -base64 32
    [YOUR_API_KEY]
  4. Spusťte wrangler secret put příkaz pro přidání API do nasazeného projektu.

    npx wrangler secret put API_KEY
    ✔ Enter a secret value:

    Terminál vás vyzve k zadání tajné hodnoty.

  5. Zadejte hodnotu svého API klíče (YOUR_API_KEY). Váš klíč API bude nyní přidán do vašeho projektu. Pomocí této hodnoty můžete provádět zabezpečená volání API na vaše nasazené API.

    ✔ Enter a secret value: [YOUR_API_KEY]
    🌀 Creating the secret for the Worker "d1-http"
    ✨ Success! Uploaded secret API_KEY
  6. Pro otestování spusťte následující příkaz cURL se správným YOUR_API_KEY a DEPLOYED_APP_LINK.

    • Použijte YOUR_API_KEY jste vygenerovali jako tajný klíč API.
    • Můžete také najít svůj DEPLOYED_APP_LINK z Cloudflare dashboardu > Workers & Pages > d1-http > Nastavení > Domains & Routes.
    curl -H "Authorization: Bearer YOUR_API_KEY" "https://DEPLOYED_APP_LINK/api/exec" --data '{"query": "SELECT 1"}'

Souhrn

V tomto tutoriálu jste:

  1. Vytvořeno API, které komunikuje s vaší databází D1.
  2. Toto API bylo nasazeno na Workers. Toto API můžete použít ve své externí aplikaci ke spouštění dotazů proti databázi D1. Úplný kód k tomuto tutoriálu najdete na GitHub.

Další kroky

Podobnou implementaci využívající Zod pro validaci najdete v tento repozitář na GitHubu. Pokud chcete pro svou databázi D1 vytvořit API kompatibilní s OpenAPI, použijte Šablona Cloudflare Workers OpenAPI 3.1.