メソッド · Cloudflare Flagship ドキュメント

Flagship バインディングは、フィーチャーフラグを評価するための次のメソッドを提供します。すべてのメソッドは非同期で、Promise を返します。既知の評価失敗では、型付きメソッドは指定した defaultValue を返します。

FlagshipEvaluationContext と FlagshipEvaluationDetails の定義は、型リファレンスを参照してください。

`get()`

型チェックなしで、フラグの生の値を返します。コンパイル時にフラグの型が分からないときに使います。

defaultValue を指定すると、フラグが見つからないなど既知の評価失敗では、その値を返します。defaultValue を省略すると、既知の評価失敗は例外になります。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`unknown`	いいえ	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getBooleanValue()`

フラグの値を boolean として返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`boolean`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getStringValue()`

フラグの値を string として返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`string`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getNumberValue()`

フラグの値を number として返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`number`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getObjectValue()`

フラグの値を型付きオブジェクトとして返します。期待する形は、ジェネリックパラメーター T で指定します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`T`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

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

`getBooleanDetails()`

フラグの値を boolean として、評価メタデータ付きで返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`boolean`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getStringDetails()`

フラグの値を string として、評価メタデータ付きで返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`string`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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()`

フラグの値を number として、評価メタデータ付きで返します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`number`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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

`getObjectDetails()`

フラグの値を型付きオブジェクトとして、評価メタデータ付きで返します。期待する形は、ジェネリックパラメーター T で指定します。

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

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	`T`	はい	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です。

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"

エラー処理

型付き評価メソッドは、フラグが見つからない、型が一致しないなど既知の評価失敗では、指定した defaultValue を返します。想定外のランタイム失敗は、引き続き例外になることがあります。既知の評価失敗を調べるには、*Details メソッドを使います。

型の不一致

型の異なるフラグに対して型付きメソッドを呼ぶと（例: string フラグに対する getBooleanValue）、メソッドはデフォルト値を返します。*Details メソッドは errorCode を "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"

評価の失敗

別の理由で評価に失敗した場合、メソッドはデフォルト値を返します。*Details メソッドには、"FLAG_NOT_FOUND"、"INVALID_CONTEXT"、"PARSE_ERROR"、"GENERAL" などの errorCode が含まれます。

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

パラメーターリファレンス

次の表は、すべての評価メソッドで共通するパラメーターをまとめたものです。

パラメーター	型	必須	説明
`flagKey`	`string`	はい	評価するフラグのキーです。
`defaultValue`	メソッドにより異なる	はい（`get` を除く）	評価に失敗したとき、またはフラグが見つからないときに返すフォールバック値です。
`context`	`FlagshipEvaluationContext`	いいえ	ターゲティングルール用のキーと値の属性です（例: `{ userId: "user-42", country: "US" }`）。