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"
}
}'