← Cloudflare Flagship / flagship / binding

Metody

Binding Flagship poskytuje následující metody pro vyhodnocování příznaků funkcí. Všechny metody jsou asynchronní a vrací Promise. U známých chyb vyhodnocení vracejí typované metody defaultValue , který poskytnete.

Viz reference typů pro definice FlagshipEvaluationContext a FlagshipEvaluationDetails.

`get()`

Vrátí nezpracovanou hodnotu příznaku bez kontroly typu. Tuto metodu použijte, pokud typ příznaku není znám v době kompilace.

Pokud zadáte defaultValue, get() vrátí tuto hodnotu při známých chybách vyhodnocení, například u chybějícího příznaku. Pokud vynecháte defaultValue, jsou vyvolány známé chyby vyhodnocení.

get(flagKey: string, defaultValue?: unknown, context?: FlagshipEvaluationContext): Promise<unknown>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`unknown`	Ne	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const value = await env.FLAGS.get("checkout-flow", "v1", {
	userId: "user-42",
});

`getBooleanValue()`

Vrátí hodnotu příznaku jako boolean.

getBooleanValue(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<boolean>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`boolean`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const enabled = await env.FLAGS.getBooleanValue("dark-mode", false, {
	userId: "user-42",
});

`getStringValue()`

Vrátí hodnotu příznaku jako string.

getStringValue(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<string>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`string`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const variant = await env.FLAGS.getStringValue("checkout-flow", "v1", {
	userId: "user-42",
	country: "US",
});

`getNumberValue()`

Vrátí hodnotu příznaku jako number.

getNumberValue(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<number>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`number`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const maxRetries = await env.FLAGS.getNumberValue("max-retries", 3, {
	plan: "enterprise",
});

`getObjectValue()`

Vrátí hodnotu příznaku jako typovaný objekt. Použijte obecný parametr T k určení očekávaného tvaru.

getObjectValue<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<T>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`T`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

interface ThemeConfig {
	primaryColor: string;
	fontSize: number;
}

const theme = await env.FLAGS.getObjectValue<ThemeConfig>(
	"theme-config",
	{ primaryColor: "#000", fontSize: 14 },
	{ userId: "user-42" },
);

`getBooleanDetails()`

Vrátí hodnotu příznaku jako boolean s metadaty vyhodnocení.

getBooleanDetails(flagKey: string, defaultValue: boolean, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<boolean>>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`boolean`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const details = await env.FLAGS.getBooleanDetails("dark-mode", false, {
	userId: "user-42",
});
console.log(details.value); // true
console.log(details.reason); // "TARGETING_MATCH"

`getStringDetails()`

Vrátí hodnotu příznaku jako string s metadaty vyhodnocení.

getStringDetails(flagKey: string, defaultValue: string, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<string>>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`string`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const details = await env.FLAGS.getStringDetails("checkout-flow", "v1", {
	userId: "user-42",
});
console.log(details.value); // "v2"
console.log(details.variant); // "new"
console.log(details.reason); // "TARGETING_MATCH"

`getNumberDetails()`

Vrátí hodnotu příznaku jako number s metadaty vyhodnocení.

getNumberDetails(flagKey: string, defaultValue: number, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<number>>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`number`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

const details = await env.FLAGS.getNumberDetails("max-retries", 3, {
	plan: "enterprise",
});
console.log(details.value); // 5
console.log(details.reason); // "TARGETING_MATCH"

`getObjectDetails()`

Vrátí hodnotu příznaku jako typovaný objekt s metadaty vyhodnocení. Použijte obecný parametr T k určení očekávaného tvaru.

getObjectDetails<T extends object>(flagKey: string, defaultValue: T, context?: FlagshipEvaluationContext): Promise<FlagshipEvaluationDetails<T>>

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	`T`	Ano	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení.

interface ThemeConfig {
	primaryColor: string;
	fontSize: number;
}

const details = await env.FLAGS.getObjectDetails<ThemeConfig>(
	"theme-config",
	{ primaryColor: "#000", fontSize: 14 },
	{ userId: "user-42" },
);
console.log(details.value); // { primaryColor: "#0051FF", fontSize: 16 }
console.log(details.variant); // "brand-refresh"

Zpracování chyb

Typované metody vyhodnocení vrací defaultValue kterou jste zadali pro známé chyby vyhodnocení, například chybějící příznak nebo neshodu typů. Neočekávané chyby za běhu mohou přesto vyvolat výjimku. Použijte *Details metody pro zjištění známých chyb vyhodnocení.

Neshoda typů

Pokud zavoláte typovanou metodu na flagu s jiným typem (například getBooleanValue na řetězcovém flagu), metoda vrátí výchozí hodnotu. *Details metody nastavují errorCode na "TYPE_MISMATCH".

// Flag "checkout-flow" is a string flag, but you call getBooleanDetails.
const details = await env.FLAGS.getBooleanDetails("checkout-flow", false);
console.log(details.value); // false (the default value)
console.log(details.errorCode); // "TYPE_MISMATCH"

Selhání vyhodnocení

Pokud vyhodnocení selže z jiného důvodu, metoda vrátí výchozí hodnotu. *Details metody obsahují errorCode jako například "FLAG_NOT_FOUND", "INVALID_CONTEXT", "PARSE_ERROR", nebo "GENERAL".

const details = await env.FLAGS.getStringDetails(
	"nonexistent-flag",
	"fallback",
);
console.log(details.value); // "fallback"
console.log(details.errorCode); // "FLAG_NOT_FOUND"

Referenční přehled parametrů

Následující tabulka shrnuje parametry společné pro všechny metody vyhodnocování.

Parametr	Typ	Povinné	Popis
`flagKey`	`string`	Ano	Klíč příznaku, který se má vyhodnotit.
`defaultValue`	liší se	Ano (kromě `get`)	Náhradní hodnota, která se vrátí, pokud vyhodnocení selže nebo příznak není nalezen.
`context`	`FlagshipEvaluationContext`	Ne	Atributy klíč-hodnota pro pravidla cílení (například `{ userId: "user-42", country: "US" }`).