INTEGRITY Документация

← Cloudflare Flagship / flagship

Начало работы

В этом руководстве вы создадите флаг функции в Flagship и выполните его оценку внутри Cloudflare Worker.

Создание приложения и флага

В этом примере вы создадите булев флаг с именем new-checkout который определяет, увидят ли пользователи новый интерфейс оформления заказа.

  1. Войдите в Панель управления Cloudflare ↗ и выберите свой аккаунт.
  2. Перейдите в Вычисления > Флагман.
  3. Выберите Создать приложение. Присвойте приложению имя, соответствующее вашему проекту или сервису (например, checkout-service).
  4. Внутри приложения выберите Create flag.
  5. Создайте булев флаг с ключом new-checkout. При необходимости добавьте правила таргетинга чтобы контролировать, кто видит флаг.
  6. Включите флаг и выберите Save.

Добавление привязки Flagship к Worker

Добавьте привязку Flagship в файл конфигурации Wrangler, чтобы Worker мог оценивать флаги через привязку.

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

Замените <APP_ID> с ID приложения, указанным в Панель управления Cloudflare ↗. binding поле задает имя, которое вы используете для доступа к Flagship в коде Worker. В этом примере привязка доступна как env.FLAGS.

После обновления конфигурации Wrangler выполните npx wrangler types чтобы сгенерировать типы TypeScript для привязки.

Оцените флаг в своём Worker

Используйте env.FLAGS привязку для оценки флага. Привязка предоставляет типобезопасные методы, которые возвращают значение флага и используют заданное вами значение по умолчанию, если оценка завершается ошибкой.

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.");
	},
};

Третий аргумент для getBooleanValue это контекст оценки. Flagship использует атрибуты контекста для сопоставления с правилами таргетинга. В этом примере userId атрибут передан, чтобы процентные постепенные релизы и таргетинг на конкретных пользователей работали корректно.

Развёртывание и тестирование

Разверните ваш Worker:

npx wrangler deploy

Проверьте оценку флага, отправив запрос:

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

Измените значение флага или правила таргетинга на панели управления и посмотрите на обновлённый ответ. Изменения флага распространяются по всему миру за несколько секунд.

(Необязательно) Используйте SDK OpenFeature

Если вы предпочитаете OpenFeature ↗ стандартный интерфейс, или, если вы работаете вне Cloudflare Worker, можете использовать @cloudflare/flagship ↗ SDK вместо привязки.

Установка SDK:

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

Оценка флагов с помощью клиента OpenFeature:

Передавайте привязку Flagship напрямую провайдеру. Это избавляет от лишних издержек HTTP и является рекомендуемым подходом внутри Worker. Привязка выполняет аутентификацию автоматически.

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.",
		);
	},
};

Используйте ID приложения, ID аккаунта и API токен при запуске вне Worker, например в Node.js. Создайте API-токен из вашего аккаунта Cloudflare с разрешением Flagship Evaluate или 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",
});

См. Документация по SDK для подробных инструкций по настройке.

Следующие шаги