CKTool JSの紹介

CKTool JSの紹介

CKTool JSを使用して、Cloudコンテナを管理および自動化する方法をご覧ください。CKTool JSを設定してコンテナのスキーマを管理したり、レコードを簡単に変更したり、データをオンザフライで操作したりする方法を紹介します。また、CKTool JSを自動化やツール使用のワークフローに統合する方法についても解説します。このセッションを最大限に活用するには、CloudKitスキーマ、JavaScript、npmに関する知識を習得しておくとよいでしょう。

リソース
関連ビデオ

WWDC22
- CloudKit Consoleの最新情報
WWDC21
- cktoolと宣言型スキーマによるCloudKitテストの自動化
- CloudKitコンソールについて
ダウンロード

CloudKitチームのエンジニアKentです CloudKitにアクセスするための新しいライブラリをご紹介しますまずライブラリの設定方法を説明しますそしてスキーマを管理する方法と CKTool JSでユーザーデータにアクセスする方法です始めましょう！
CloudKitは Appのデータをコンテナ内の iCloudに保存できる永続化テクノロジーです CloudKitを使用することでデバイス間およびWeb上でデータを最新の状態に保つこともできます Appを構築するためにAppleプラットフォームの CloudKitフレームワーク WebのCloudKitJSを使って iCloudストレージにアクセスできます自動化とツールを実装するためにXcodeは CKTool JSを使用して変更を自動化し iCloudと対話できます
CKTool JSはcktoolコマンドラインユーティリティと同じ操作を実行でき同様のユースケースをサポートします CKTool JSはCloudKit Consoleのレコードタイプ追加やレコードの問い合わせなどの機能を実装します
CKTool JSを使用するとAppコンテナを管理しスキーマのリセットや適用などのスキーマ操作を実行することができますこれまでJavaScriptでは実行できませんでした
CKTool JSでは既存のレコードを一意の識別子でまたは複雑なクエリを通じて取得することができます新しいレコードを作成したり更新もできます CKTool JSはTypeScriptの厳密な型定義が付属しますこの型定義でクライアントライブラリの誤った使用にフラグを立てるコンパイル時のチェックが可能になりサポートしているIDEでのコード補完が可能になりますこのためCKToolJSコードの編集が簡単になります
さらにこの新しいライブラリには Node.jsとブラウザの両方がサポートされています CKTool JSはnpmパッケージのセットとして配布され JavaScriptのビルドパイプラインに統合しますツリーシェイクやバンドル等の機能が可能になりますパッケージのリリース履歴は npmから透過的に入手してパッケージの更新を追跡することも可能です
次はCKToolJSディストリビューションですこれらのパッケージは@appleスコープ内にあり
名前の先頭にcktool dotを使用する規則に従います主なパッケージはcktooldotデータベースです iCloudとの通信を有効にしてターゲットプラットフォーム用にもう1つのパッケージ Node.js用のcktool dot Target dot nodejs
またはWebブラウザ用の Cktool dot target dotブラウザも使用する必要があります CKToolJSは直接通信するため iCloudでは最初に認証します呼び出したい操作に応じて管理者トークンまたはユーザートークンが必要になりますどちらも CloudKit Consoleから取得可能です
管理トークンは管理操作にアクセスするためのものでチームとユーザーを対象にしていますスキーマのインポートとエクスポートの有効化スキーマの検証コンテナの実稼働リセットが含まれますユーザートークンはチームとコンテナ対象でプライベートユーザーデータアクセスを可能にします認証トークンを取得する方法と CloudKitとの継続的インテグレーションについては WWDC21「cktoolと宣言型スキーマによる CloudKitテストの自動化」をご覧ください
スクリプトでCKToolJSを使用する場合は最初に使用するように構成します CKTool JSの構成に入る前に CloudKitスキーマを構成するものについて説明します CloudKitではデータは構造化されて保存されます同種の値のIDataはレコードとして一緒に格納されますレコードはレコードタイプのインスタンスでありレコードタイプが記述するレコードのプロパティはフィールドと呼ばれます CloudKitはユーザー定義フィールドに加えて recordNameなどのシステムフィールドを追加しますコインコレクションAppの例を使用します国のコレクション保存のため記述用のレコードタイプがあります名前とISOコードを保存してレコードの種類に「国」と名前をつけます ISOコードは国を識別するためレコードタイプに含めることが重要です
名前とともに保存するために国タイプのレコードをいくつか作成します
特定の国のコインのレコードタイプもありそれらを相互に関連付けたいと思いますコインからその国までの関係を格納します
これらを組み合わせてスキーマを作成しますこれらの要素の現在の状態が私のスキーマの現在のバージョンであると考えることができますスキーマは進化しAppの寿命が尽きるまでいくつかのバージョンに別れるでしょう
スキーマはiCloudに保存したいデータの構造を記述コンテナはそのデータが保存される場所ですコンテナには開発チームに関連づける識別子があります CloudKitを使用する際に2つの環境があります開発環境はユーザーを混乱させることなく変更を加えるための安全な場所ですここでスキーマの変更をテスト開発する必要がありますユーザーがAppを操作すると本番環境を操作することになりますここにはAppのライブデータが含まれています CloudKitのデータ保存方法を確認したところで CKTool JSの設定方法について説明します. CKTool JSはiCloudと通信するため適切なコンテナの操作方法を認識しスクリプトが許可されるように情報を収集する必要があります
作業するコンテナのチームIDとコンテナIDが必要になりますスキーマを操作するには管理トークンスクリプトがデータにアクセスする時はユーザートークンが必要です値はすべてCloudKitコンソールから取得しますスクリプトを実行する環境開発または本番環境を指定する必要があります今後は開発を例に挙げて説明します CKTool JSを設定するときはこれらの値が必要です私はNode.jsのスクリプトを書いています CKTool JSからオブジェクトや関数をインポートします CommonJSのrequire文を使いシンボルをインポートします設定情報を集めたら情報を保持するオブジェクトを作成します認証トークンを格納するため管理トークンと可能ならユーザートークンを格納するオブジェクトを作成します teamId containerId environmentはCKToolJSに渡す共通の値で保持するオブジェクトを作成できます createConfiguration関数を使って CKToolJSに Configurationオブジェクトをインスタンス化します createConfigurationはプラットフォーム固有です Node.jsはターゲットパッケージからインポートした関数であるため適切な構成が返されます先に宣言した構成オブジェクトとセキュリティオブジェクトを渡し APIオブジェクトを初期化しますこれにはiCloudと通信する非同期メソッドが含まれますスクリプトでCKToolJSを使う手順が完了しました CKToolJSを使用してコンテナのスキーマを管理する方法について学びましょう 2007年に発行されたアメリカの 10セント硬貨などの情報を保存したいと思いますこの硬貨は銅とニッケルで構成されており刻印されている金額は米ドルの1/10ですデータの保存方法を考えた結果コインの構成に関する情報をコインに関する他の詳細とは別のレコードとして保存することにしましたそのため10セント硬貨の銅の割合と硬貨のニッケルの割合を別々のレコードに保存しますコンテナのスキーマに必要な 2つのレコードタイプを特定しました貨幣は国名発行年額面金額を記録していますコンポーネントレコードタイプはコインの名前と説明コインに含まれる材料とその割合を保存します Appのスキーマが決まったので CloudKit Schema Languageでテキストファイルを作りますスキーマファイルには .ckdb 拡張子を使用します
CloudKit Schema Languageについては「Integrating a Workflow Text-Based Schema into Your Workflow」を参照してください
コンテナ用スキーマファイルはCKTool JSで適用します新しいスキーマを適用する前にコンテナの開発用スキーマをリセットして本番用のスキーマと一致させます resetToProduction メソッドで行うことができますメソッドを呼び出すには先ほど宣言した defaultArgsオブジェクトを渡しますスキーマが本番環境でないと全レコードタイプ削除です本番環境ではない場合は開発用スキーマを本番環境の状態に戻すことになります非同期呼び出しなのでプロミスオブジェクトを返す
ことに注意してくださいCKTool JSはコンテナのスキーマをエクスポートインポートできます exportSchemaとimportSchemaを使用するとコンテナの観点から名前が付けられますコンテナからエクスポートするスキーマを exportSchemaでダウンロードしコンテナにインポートするスキーマを importSchemaでアップロードしますこれらを組み合わせることでスキーマの進化を管理することができます
コンテナにスキーマを適用するヘルプ関数を作成します CKTool JSからFileオブジェクトをインポートし Node.jsからfsモジュールと pathモジュールをインポート以下のような非同期関数を定義してくださいスキーマファイルをNode.js のバッファに読み込みますアップロード用のCKTool JS Fileのインスタンスを作り importSchema を使いサーバーにファイルをアップします宣言したdefaultArgsオブジェクトを importSchemaに渡していることに注意してくださいこれで組み立てることができます resetToProductionとスキーマのインポートに使うヘルプ関数は非同期なので正しい順序で実行しますそのために約束事を連鎖させますエラーが発生した場合は拒否されます CKTool JSが持つ管理機能だけでなくデータの読み書きを行うこともできます CKTool JSレコードで使うフィールド値はサーバーに送信される前にクライアント側でタイプと範囲をチェックされます値が正しい種類の値でないか値の許容範囲外である場合例外がスローされます JavaScriptで表現できない大きな数の場合代わりに使用されるCKToolJSタイプがあります番号をCKTool JS Int64に強制変換するには toInt64関数を使用します数値を倍精度浮動小数点値に強制変換するには toDouble関数を使用します TypeScriptを作成中に強制関数を使わない場合コンパイラは誤った値型の使用にフラグを立てます
CKTool JSレコードのフィールド値はフィールド値ファクトリ関数を使用して作成します 2007年に発行されたコインの場合 Int64を含むレコードフィールド値を作るために makeRecordFieldValuedotint 64ファクトリ関数に渡しますファクトリ関数が渡された値からレコードフィールド値を作成できない場合例外がスローされます
レコードを処理するメソッドに送信する共通の値を保持するオブジェクトを作成しました containerId environment databaseType zoneNameを databaseArgsオブジェクトに含めます queryRecordsメソッドでレコード照会をします簡単にするために固有の3文字のISOコードに一致する国を見つけるヘルパー関数を作成しますクエリを含む本文に加えて databaseArgsオブジェクトのコンテンツを渡しますクエリオブジェクトにはrecordType値と単一のフィルターオブジェクトを指定しています filterオブジェクトは国のisoCode3が関数が求めているものと等しいクエリを記述します成功した場合見つかったレコードのコレクションは応答ドット結果ドットレコードプロパティにありますこのコレクションから最初のオブジェクトを返します
createRecordが使用できるフィールド値に変換するためにヘルパー関数makeCoinFieldValuesを使いますコインの生のプロパティのうちフィールド値に変換するにはレコードフィールドファクトリ関数を使います国名フィールドについては参照を作成します国別レコード名を使ってコインレコードから対応する国のレコードを参照します
コインレコードフィールド値を取得して createRecord リクエストをサーバーに送るヘルパー関数を作成しますこの関数では以前に宣言したdatabaseArgsのコンテンツと本体を渡します本文ディクショナリには recordTypeとィールドの値が含まれています成功したら応答ドット結果ドットレコードが返ります
ヘルパー関数を呼び出す前にこのコインから参照される正しい国のレコードを取得する必要があります前に定義した国クエリ関数を使用します makeCoinFieldValuesヘルパー関数で作成したフィールド値ディクショナリを渡してcoinCreateRecordを呼び出します生のコインの値はそのヘルパー関数に渡されます非同期でレコードが作成され新しいレコードが返されます
更新するにはupdateRecord メソッドを使用しますレコード名とこのヘルパーに渡されたフィールドに一致するコインを更新するヘルパー関数を作成します databaseArgsオブジェクト recordName レコードタイプと本文の内容を使用して updateRecordを呼び出します成功すると　更新レコードはヘルパー関数から返される応答ドット結果ドットレコードプロパティに含まれます
コインレコードを更新する為ヘルパー関数を呼び出しレコード名とフィールド値を渡して更新しますフィールド値はmakeCoin FieldValuesで作成します
レコード削除には非同期 deleteRecordを呼び出します databaseArgsオブジェクトの内容と削除するrecordNameを渡します CKToolJSを楽しんでいただけたでしょうかご自分でも試してみてください自動化とツールの目的でCKToolJSを構成しますスキーマをリセットしてインポートし JavaScriptを使用してデータを読み書きします継続的インテグレーションシナリオのCKToolJS使用は GitHubのCloudKitサンプルリポジトリをご確認ください詳細はdeveloper.apple.comの CKToolJSをご覧くださいご参加ありがとうございます WWDC22をお楽しみください

6:43 - Create security and default arguments objects

// Create security object and setup default args

const { CKEnvironment } = require("@apple/cktool.database");

const security = {
    "ManagementTokenAuth": "<YOUR_MANAGEMENT_TOKEN>",
    "UserTokenAuth": "<YOUR_USER_TOKEN>"
};

const defaultArgs = {
    "teamId": "<YOUR_TEAM_ID>",
    "containerId": "<YOUR_CONTAINER_ID>",
    "environment": CKEnvironment.DEVELOPMENT
};

7:17 - Create configuration and API objects

// Create configuration and API objects

const { createConfiguration } = require("@apple/cktool.target.nodejs");
const { PromisesApi } = require("@apple/cktool.database");

const configuration = createConfiguration();
const api = new PromisesApi({
    "configuration": configuration,
    "security": security
});

10:00 - Reset to production and import schema

// Create a function to apply a schema

const { File } = require("@apple/cktool.target.nodejs");
const fs = require("fs/promises");
const path = require("path");

const importMySchema = async () => {
    const schemaPath = "<YOUR_SCHEMA_FILE>.ckdb";
    const buffer = await fs.readFile(schemaPath);
    const file = new File([buffer], schemaPath);
    await api.importSchema({ ...defaultArgs, "file": file });
}

// Chain the calls
api.resetToProduction(defaultArgs)
  .then(() => importMySchema());

11:36 - Factory functions

// Create fields with factory functions.

const {
    makeRecordFieldValue
} = require("@apple/cktool.database");

const value = makeRecordFieldValue.int64(2007);

12:02 - Create database arguments object

// Create a database arguments object.

const {
    CKDatabaseType, CKEnvironment
} = require("@apple/cktool.database");

const databaseArgs = {
    "containerID": "<YOUR_CONTAINER_ID>",
    "environment": CKEnvironment.DEVELOPMENT,
    "databaseType": CKDatabaseType.PRIVATE,
    "zoneName": "_defaultZone"
};

12:16 - Query for records

// Define helper function for querying records

const { CKDBQueryFilterType } = require("@apple/cktool.database");
const countryQueryRecordForCountryCode3 = async (countryCode3) => {
    const response = await api.queryRecords({
        ...databaseArgs,
        "body": {
            "query": {
                "recordType": "Countries",
                "filters": [{
                    "fieldName": "isoCode3",
                    "fieldValue": makeRecordFieldValue.string(countryCode3),
                    "type": CKDBQueryFilterType.EQUALS
                }]
            }
        }
    });
    return response.result.records[0];
}

12:58 - Create field values

// Define a helper function for creating field values

const {
    makeRecordFieldValue, CKDBRecordReferenceAction
} = require("@apple/cktool.database");

const makeCoinFieldValues = ({ countryRecordName, issueYear, nominalValue }) => ({
    "country": makeRecordFieldValue.reference({
        recordName: countryRecordName,
        action: CKDBRecordReferenceAction.DELETE_SELF
    }),
    "issueYear": makeRecordFieldValue.int64(issueYear),
    "nominalValue": makeRecordFieldValue.double(nominalValue)
});

13:26 - Create a record

// Define helper method for creating coins

const coinCreateRecord = async (fields) => {
    const response = await api.createRecord({
        ...databaseArgs,
        "body": {
            "recordType": "Coins",
            "fields": fields
        },
    });
    return response.result.record;
}

13:48 - Call record creation helper method

// Call coin creation method with field values

const countryRecord = await countryQueryRecordForCountryCode3("USA");

const coinRecord1 = await coinCreateRecord(
    makeCoinFieldValues({
        "countryRecordName": countryRecord.recordName,
        "issueYear": 2007,
        "nominalValue": 0.10
    })
);

14:16 - Define update record helper function

// Define helper method for updating coins.
// Note that recordChangeTag is required

const coinUpdate =
    async (recordName, recordChangeTag, fields) => {
        const response = await api.updateRecord({
            ...databaseArgs,
            "recordName": recordName,
            "body": {
                "recordType": "Coins",
                "recordChangeTag": recordChangeTag,
                "fields": fields
            }
        });
        return response.result.record;
    }

14:44 - Update a record with field values

// Call coin updating method with field values.
// Note that the recordChangeTag of the record
// to update is passed to the coin update function.

const countryRecord = await countryQueryRecordForCountryCode3("USA");
const updatedCoinRecord1 = await coinUpdate(
    coinRecord1.recordName,
    coinRecord1.recordChangeTag,
    makeCoinFieldValues({
        "countryRecordName": countryRecord.recordName,
        "issueYear": 2010,
        "nominalValue": 0.10
    });
);

14:57 - Delete a record

// Deleting a record

await api.deleteRecord({
    ...databaseArgs,
   "recordName": coinRecord1.recordName
});

特定のトピックをお探しの場合は、上にトピックを入力すると、関連するトピックにすばやく移動できます。

クエリの送信中にエラーが発生しました。インターネット接続を確認して、もう一度お試しください。

リソース

関連ビデオ

WWDC22

WWDC21