cktoolの使用方法

事前の確認

• cktoolを使用するには、現在Apple Developer ProgramまたはApple Developer Enterprise Programのメンバーである必要があります。
• 「CloudKit開発を自動化する」で説明されている認証の概念をよく理解しておきます。
• ユーザーアカウントの「Settings（設定）」セクションを選択し、CloudKit ConsoleからCloudKit管理トークンを生成します。このトークンはあとで再表示できないため、必ず保存してください。

アプリのインストール

デフォルトでは、cktoolはXcodeと一緒に配信されます（Xcode 13以降）。XcodeはMac App Storeで入手できます。

一般的な使い方

cktoolはステートレスであり、すべての操作を1回の操作でCloudKit Management APIに渡します。サポートされている操作すべての一覧は、helpコマンドまたはmanページで確認できます。

xcrun cktool --help
OVERVIEW: CloudKit Command Line Tool

USAGE: cktool <subcommand>

OPTIONS:
	-h, --help				Show help information.

SUBCOMMANDS: ...

CloudKitに対するcktoolの認証

cktoolは、管理トークンとユーザートークンの両方をサポートしており、これらのトークンはMacのキーチェーンに安全に保管されます。トークンを追加するには、save-tokenコマンドを使います。このコマンドは、ユーザーに情報の入力を求めたあとで、適切なトークンをコピーするためにCloudKit Consoleを起動します。

xcrun cktool save-token			\
	--type [management | user]

スキーマ管理コマンドの発行

スキーマ管理コマンドを使うには、管理トークンを指定する必要があります。トークンを指定すると、cktoolは以下のコマンドを実行できます。

開発環境のスキーマのリセット：開発環境のデータベースを最新のプロダクション環境の定義に戻すことができます。

xcrun cktool reset-schema	\
	--team-id [TEAM-ID]		\
	--container-id [CONTAINER]

スキーマファイルのエクスポート：既存のCloudKitデータベーススキーマ定義をファイルに保存できます。このファイルは関連するソースコードと一緒に保持できます。

xcrun cktool export-schema 		\
	--team-id [TEAM-ID]			\
	--container-id [CONTAINER]	\
	--environment [development | production]	\
	[--output-file schema.ckdb]

スキーマファイルのインポート：テストのために、開発環境のデータベースにファイルベースのスキーマ定義を適用します。

xcrun cktool import-schema 		\
	--team-id [TEAM-ID]			\
	--container-id [CONTAINER]	\
	--environment development 	\
	--file schema.ckdb

データコマンドの発行

ユーザートークンを利用できる場合、cktoolはユーザーに代わってパブリックデータベースやプライベートデータベースにアクセスできます。この操作は、統合テストの前に、データをフェッチして新しいレコードを挿入するために使用できます。ユーザートークンは有効期間が短いため、頻繁にインタラクティブ認証が必要になる場合があります。

レコードの照会を実行するには、query-recordsコマンドを使用します。フィルターなしで照会を行う場合、任意の--filters引数に指定するフィールドと同様に、Queryableインデックスを適用するための___recordIDが必要です。

xcrun cktool query-records		\
	--team-id [TEAMID] 			\
	--container-id [CONTAINER] 	\
	--zone-name [ZONE_NAME] 		\
	--database-type [public | private] 	\
	--environment [development | production]	\
	--record-type [RECORD_TYPE]	\
	[--filters [FILTER_1] [FILTER_2]]

ここで、FILTER_1は"[FIELD_NAME] [OPERATOR] [VALUE]"の形式です。例えば、"lastname == Appleseed"とします。

データを挿入するには、create-recordコマンドを使用します。

xcrun cktool create-record		\
	--team-id [TEAM_ID]			\
	--container-id [CONTAINER]	\
	--zone-name [ZONE_NAME] 		\
	--database-type [public | private] 	\
	--environment [development | production]	\
	--record-type [RECORD_TYPE]	\
	[--fields-json [FIELDS_JSON]]

ここで、FIELDS_JSONはレコードに設定するフィールドのJSON表現です。以下はその例です。

'{
	"firstName": {
	"type": "stringType",
	"value": "Johnny"
 },
	"lastName": {
	"type": "stringType",
	"value": "Appleseed"
 }
}'