INTEGRITY Dokumentace

← Cloudflare Flagship / flagship

Začínáme

V tomto průvodci vytvoříte feature flag ve Flagship a vyhodnotíte ho uvnitř Cloudflare Workeru.

Vytvoření aplikace a příznaku

V tomto příkladu vytvoříte boolean flag s názvem new-checkout který určuje, zda uživatelé uvidí novou zkušenost s pokladnou.

  1. Přihlaste se do Cloudflare dashboard ↗ a vyberte svůj účet.
  2. Přejděte na Compute > Vlajková loď.
  3. Vyberte Vytvořit aplikaci. Aplikaci pojmenujte tak, aby odpovídala vašemu projektu nebo službě (například checkout-service).
  4. Uvnitř aplikace vyberte Vytvořit příznak.
  5. Vytvořte booleovský příznak s klíčem new-checkout. Volitelně přidejte cílicí pravidla k určení, kdo příznak uvidí.
  6. Zapněte flag a vyberte Save.

Přidání vazby Flagship do Workeru

Přidejte vazbu Flagship do konfiguračního souboru Wrangleru, aby mohl váš Worker vyhodnocovat příznaky prostřednictvím vazby.

{
	"flagship": [
		{
			"binding": "FLAGS",
			"app_id": "<APP_ID>",
		},
	],
}
[[flagship]]
binding = "FLAGS"
app_id = "<APP_ID>"

Nahraďte <APP_ID> s ID aplikace zobrazeným v Cloudflare dashboard ↗. binding pole nastavuje název, pod kterým budete přistupovat k Flagship ve svém kódu Workeru. V tomto příkladu je binding dostupný jako env.FLAGS.

Po aktualizaci konfigurace Wrangleru spusťte npx wrangler types ke generování typů TypeScript pro vazbu.

Vyhodnoťte příznak ve svém Workeru

Použijte env.FLAGS binding pro vyhodnocení flagu. Binding poskytuje typově bezpečné metody, které vrátí hodnotu flagu, a pokud vyhodnocení selže, vrátí výchozí hodnotu, kterou zadáte.

export default {
	async fetch(request, env) {
		const url = new URL(request.url);
		const userId = url.searchParams.get("userId") ?? "anonymous";

		const showNewCheckout = await env.FLAGS.getBooleanValue(
			"new-checkout",
			false,
			{ userId },
		);

		if (showNewCheckout) {
			return new Response("Welcome to the new checkout experience!");
		}

		return new Response("Standard checkout.");
	},
};
export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		const url = new URL(request.url);
		const userId = url.searchParams.get("userId") ?? "anonymous";

		const showNewCheckout = await env.FLAGS.getBooleanValue(
			"new-checkout",
			false,
			{ userId },
		);

		if (showNewCheckout) {
			return new Response("Welcome to the new checkout experience!");
		}

		return new Response("Standard checkout.");
	},
};

Třetí argument getBooleanValue je kontext vyhodnocení. Flagship používá atributy kontextu k porovnání s cílicími pravidly. V tomto příkladu userId atribut je předán, aby procentuální rollouty a cílení na konkrétní uživatele fungovaly správně.

Nasazení a testování

Nasaďte svůj Worker:

npx wrangler deploy

Otestujte vyhodnocení příznaku odesláním požadavku:

curl "https://<YOUR_WORKER>.<YOUR_SUBDOMAIN>.workers.dev/?userId=user-42"

Změňte hodnotu příznaku nebo cílicí pravidla v dashboardu a sledujte aktualizovanou odpověď. Změny příznaků se globálně projeví během několika sekund.

(Volitelné) Použijte OpenFeature SDK

Pokud preferujete OpenFeature ↗ standardní rozhraní, nebo pokud běžíte mimo Cloudflare Worker, můžete použít @cloudflare/flagship ↗ SDK místo bindingu.

Instalace SDK:

npm i @cloudflare/flagship @openfeature/server-sdk

Vyhodnocení příznaků pomocí klienta OpenFeature:

Předejte vazbu Flagship přímo poskytovateli. Vyhnete se tak zbytečné zátěži HTTP a jde o doporučený postup uvnitř Workeru. Vazba se o ověřování stará automaticky.

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request, env) {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42" },
		);

		return new Response(
			showNewCheckout ? "New checkout!" : "Standard checkout.",
		);
	},
};
import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

export default {
	async fetch(request: Request, env: Env): Promise<Response> {
		await OpenFeature.setProviderAndWait(
			new FlagshipServerProvider({ binding: env.FLAGS }),
		);

		const client = OpenFeature.getClient();

		const showNewCheckout = await client.getBooleanValue(
			"new-checkout",
			false,
			{ targetingKey: "user-42" },
		);

		return new Response(
			showNewCheckout ? "New checkout!" : "Standard checkout.",
		);
	},
};

Použijte ID aplikace, ID účtu a API token, pokud běžíte mimo Worker (například v Node.js). Vygenerujte API token z vašeho účtu Cloudflare s oprávněním Flagship Evaluate nebo Flagship App Evaluate.

import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
});
import { OpenFeature } from "@openfeature/server-sdk";
import { FlagshipServerProvider } from "@cloudflare/flagship/server";

await OpenFeature.setProviderAndWait(
	new FlagshipServerProvider({
		appId: "<APP_ID>",
		accountId: "<ACCOUNT_ID>",
		authToken: "<API_TOKEN>",
	}),
);

const client = OpenFeature.getClient();

const showNewCheckout = await client.getBooleanValue("new-checkout", false, {
	targetingKey: "user-42",
});

Viz Dokumentace SDK s podrobnými pokyny k nastavení.

Další kroky