← Cloudflare D1 / d1 / tutorials
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
- Zaregistrujte si účet Cloudflare ↗.
- Nainstalujte
Node.js↗. - 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.
-
Vytvořte Worker s názvem
d1-httpspuštěním:npm create cloudflare@latest -- d1-httpPř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).
- Pro S čím byste chtěli začít?, vyberte
-
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.
-
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.
-
Pro lokální vývoj vytvořte
.dev.varssoubor v kořenovém adresářid1-http. -
Do souboru přidejte svůj API klíč následujícím způsobem.
.dev.varsAPI_KEY="YOUR_API_KEY"Nahraďte
YOUR_API_KEYs 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:
- Bearer Auth ↗: Přidá do API autentizaci.
- Logger ↗: Umožňuje sledovat tok požadavků a odpovědí.
- Formátovaný JSON ↗: Zapne "JSON pretty print" pro těla JSON odpovědí.
-
Nahraďte obsah
src/index.tssoubor kódem níže.src/index.tsimport { 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
-
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
- POST
-
Vývojový server spustíte zadáním následujícího příkazu:
npm run dev -
Pro lokální otestování API otevřete druhý terminál.
-
Ve druhém terminálu spusťte níže uvedený příkaz cURL. Nahraďte
YOUR_API_KEYs 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 -
Místní server zastavíte stisknutím
xv 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.
-
V terminálu spusťte:
npx wrangler d1 create d1-http-exampleMož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
-
Z vašeho
d1-httpsložku, otevřete soubor Wrangler, konfigurační soubor nástroje Wrangler. -
Do souboru přidejte následující vazbu. Ujistěte se, že
database_nameadatabase_idjsou 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" -
Ve vašem
src/index.tssoubor a aktualizujteBindingstyp přidánímDB: 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:
-
Vytvořte novou složku s názvem
schemasuvnitř vašehod1-httpsložka. -
Vytvořte nový soubor s názvem
schema.sql, a do souboru vložte následující příkaz SQL.schema.sqlDROP 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
postspokud existuje, a poté vytvoří novou tabulkupostss polemid,author,title,body, apost_slug. Poté pomocí příkazu INSERT naplní tabulku daty. -
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.
-
Ve vašem
src/index.tssoubor 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í.
- Pokud je dotaz úspěšný, obdržíte výsledek z databáze.
- Pokud dojde k chybě, vrátí se chybová zpráva.
10. Otestujte API
Nyní, když API umí dotazovat databázi, ho můžete otestovat lokálně.
-
Vývojový server spustíte pomocí následujícího příkazu:
npm run dev -
V novém okně terminálu spusťte následující příkazy cURL. Nezapomeňte nahradit
YOUR_API_KEYse správnou hodnotou./api/allcurl -H "Authorization: Bearer YOUR_API_KEY" "http://localhost:8787/api/all" --data '{"query": "SELECT title FROM posts WHERE id=?", "params":1}'/api/batchcurl -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/execcurl -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.
-
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 --remoteNyní byste měli vidět tabulku na Cloudflare dashboard > Storage & Databases > D1. ↗
-
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. -
Vygenerujte nový API klíč pro použití v produkčním prostředí.
openssl rand -base64 32[YOUR_API_KEY] -
Spusťte
wrangler secret putpří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.
-
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 -
Pro otestování spusťte následující příkaz cURL se správným
YOUR_API_KEYaDEPLOYED_APP_LINK.- Použijte
YOUR_API_KEYjste vygenerovali jako tajný klíč API. - Můžete také najít svůj
DEPLOYED_APP_LINKz 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"}' - Použijte
Souhrn
V tomto tutoriálu jste:
- Vytvořeno API, které komunikuje s vaší databází D1.
- 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 ↗.