iOS 27のApp Intents：バックグラウンド実行、同期、Spotlight

App Intentsは、Shortcuts、Siri、Spotlight向けに型付けされた構造化アクションのAPIとして、iOS 16で登場しました。iOS 17ではApp Intents駆動のウィジェットへと広がり、iOS 18ではApple Intelligenceのアクション基盤を支える契約となり、iOS 26ではVisual Intelligenceやインタラクティブなスニペットにまで踏み込みました。iOS 27は、その賭けの形を再び変えます。今回の変化は見た目を整えるものではなく、機構そのものに踏み込むものです。インテントは30秒というバックグラウンド制限を超えて実行できるようになり、エンティティはユーザーのデバイス間を渡っても保たれる同一性を持てるようになり、クエリはシステムから求められたときに自らのSpotlightインデックスを修復できるようになりました。iOS 27が加えるのは、装飾ではなく能力です。¹

これまでのリリースはどれも、あなたのインテントを「誰が」呼び出せるかを広げてきました。iOS 27が広げるのは、「呼び出されたインテントが何をできるか」です。数千件のレコードを扱う同期インテントは、かつて30秒のタイマーと競争しては敗れていました。いまや、システムにより長い猶予を求め、作業中に進捗を報告できます。iPhoneでは一つのものを指し、Macでは別のものを指していたエンティティが、両方で同じオブジェクトに解決されるようになりました。本稿では、すでにApp Intentsを搭載しているアプリが各新機能を得るために何を加えればよいのか——クラスタの他の記事と同じ視点で、Appleのドキュメントに沿ってiOS 27の全体像をたどります。

要点

• LongRunningIntentは、インテントのバックグラウンド実行時間をシステムの30秒制限を超えて延長します。作業をperformBackgroundTask(options:operation:)でラップし、LongRunningTaskOptionsを渡します。このプロトコルはProgressReportingIntentを継承しているため、進捗報告は選択肢ではなく必須要件です。Live Activitiesがその進捗を自動的に描画します。²³⁴
• SyncableEntityは、AppEntityがユーザーのデバイス間で一貫した識別子を持つことを宣言します。これによりシステムは、iPhone、Mac、Watchで同じオブジェクトを参照できます（Siriはこれを使って会話をあるデバイスから別のデバイスへ引き継ぎます）。⁵
• IndexedEntityQueryは、EntityQueryにSpotlightの再インデックス対応を加えます。システムがアプリのインデックスに問題を検知したとき、該当するエンティティを再ドネートするようクエリに求められるようになります。⁶
• AppUnionValueとAppUnionValueCasesProviding（@UnionValueマクロが生成します）により、一つのパラメータが複数の異なるエンティティ型を受け取れるようになり、適切なピッカーUIとパラメータサマリーが付きます。⁷⁸
• OwnershipProvidingEntity、EntityOwnership、EntityCollectionは、所有権を踏まえた確認と一括処理の効率を扱います。RunSystemShortcutIntentとIntentExecutionTargetsは、ウィジェットから起動するシステムアクションと、どのプロセスがインテントを実行するかを扱います。^910111213

30秒の壁：LongRunningIntent

バックグラウンド実行の制限は、App Intentにできることの静かな天井でした。システムがインテントをバックグラウンドで実行するとき（ユーザーがSiriに同期を頼み、その後で端末をロックしてポケットにしまう、といった場面）、従来は完了までにおよそ30秒が与えられてきました。² コップ一杯の水を記録するなら十分すぎる時間です。しかしライブラリの同期、オンデバイス推論、大きなファイルの処理となると、30秒はギロチンです。システムは書き込みの途中でタスクを打ち切り、ユーザーには中途半端な結果が残ります。

iOS 27はLongRunningIntentを導入しました。これは、延長されたバックグラウンドの時間枠をシステムに求めるために、インテントが採用するプロトコルです。² Appleはドキュメントでユースケースを具体的に挙げています。ファイル操作、データ同期、機械学習の推論、そして十分に大きなデータセットに対するデータ処理です。宣言を見れば、一行も書かないうちに最も重要な制約がわかります。

protocol LongRunningIntent : ProgressReportingIntent

LongRunningIntentはProgressReportingIntentを継承しています。² 設計上、進捗を報告せずに長時間実行プロトコルを採用することはできません。延長された実行時間はシステムが条件付きで与える特権であり、その条件とは、いまどこまで進んだかをシステムに伝え続けることです。報告をやめれば、システムは延長を取り消し、タスクを早めに終了させることができます。³

作業はperformBackgroundTask(options:operation:)の内側に入れます。

@discardableResult
func performBackgroundTask<T>(
    options: LongRunningTaskOptions = [],
    operation: @escaping () async throws -> T
) async throws -> T

このメソッドはインテントのperform()本体から呼び出し、重い処理をoperationクロージャに入れます。このメソッドは、30秒制限を課すプラットフォーム上で、標準の制限を超えて実行時間を自動的に延長します。別のバックグラウンドタスクを開始したり、UIBackgroundTaskIdentifierを自分で管理したりする必要はありません。³ ライブラリ同期のインテントは次のようになります。

import AppIntents

struct SyncLibraryIntent: LongRunningIntent {
    static var title: LocalizedStringResource = "Sync Library"

    func perform() async throws -> some IntentResult {
        try await performBackgroundTask(options: []) {
            let records = try await server.fetchPendingRecords()
            for (offset, record) in records.enumerated() {
                try await store.apply(record)
                progress.completedUnitCount = Int64(offset + 1)
                progress.totalUnitCount = Int64(records.count)
            }
            return ()
        }
        return .result()
    }
}

チュートリアルが省きがちな二点に、説明が要ります。

progressプロパティはテレメトリではなく契約です。 Appleは明言しています。操作の実行中はProgressReportingIntent準拠が提供するProgressを定期的に更新すること、そして更新しなければシステムは実行時間の延長を取り消してタスクを早めに終了できる、と。³ 通常のインテントでの進捗報告は気の利いた付加要素にすぎません。LongRunningIntentでは、延長を生かし続ける鼓動なのです。

LongRunningTaskOptionsはリソース要件を宣言します。 このオプション値（既定が[]のOptionSet形式の構造体）は、タスクに追加で必要なリソースをシステムに伝え、システムはそれを与える実行時間に反映します。⁴ 空のセットが一般的なケースです。明示的なオプションに手を伸ばすのは、作業が既定のプロファイルを超えるリソースを必要とするときです。

30秒を越えて生き延びる以上の見返りがあります。Live Activitiesが進捗を無償で描画してくれるのです。ドキュメントによれば、Live ActivitiesはperformBackgroundTaskから自動的に受け取る情報を使ってインテントのタスクの進捗を表示し、あなたのコードが報告した値からタイトル、サブタイトル、進捗バーを描き出します。³ 音声で開始された長い同期は、Live Activityのビューを一つも作らなくても、ロック画面にライブの進捗バーとして現れます。インテントが報告し、システムが描画するのです。

セッション345でAppleは、LongRunningIntentを実際の失敗例——30秒の枠内で死に続けていた写真アップロード——に対して実演し、システムがバックグラウンドタスクのライフサイクルを管理しながら、進捗とキャンセル操作をLive Activityとして提示する様子を示しています。¹⁴

一貫した同一性：SyncableEntity

AppEntityにはidがあります。単一のデバイス上では、その識別子はアプリ内で一意であればよいだけです。問題が始まるのは、ユーザーが複数のデバイスを持った瞬間です。そしてAppleのエコシステムでは、それが既定の状態です。ユーザーがiPhoneでSiriと話した「Project Atlas」は、Macで会話を再開したときにも、それとわかる「同じ」Project Atlasでなければなりません。iPhoneのローカルな識別子がMacのものと違えば、システムには無関係な二つのオブジェクトがあるだけで、結びつける手立てがありません。

SyncableEntityがiOS 27の答えです。⁵

protocol SyncableEntity : AppEntity

これを採用すると、エンティティの識別子がデバイス間で同一であることを宣言したことになります。このプロトコルが存在するだけで、システムはあるデバイスから別のデバイスへ、あなたのエンティティを一貫して参照できると判断します。Appleは具体的な見返りを示しています。Siriはこの能力を使って、会話をあるデバイスから別のデバイスへ移します。⁵

採用のコストは、識別子がどこから来るかにすべて依存します。エンティティがすでにデバイス間で安定した識別子（サーバーが発行したUUID、iCloudのレコード名）を使っているなら、ほかに何も変えずにSyncableEntityを採用できます。すでに保存している値が、そのままシステムの必要とする値だからです。⁵

import AppIntents

struct ProjectEntity: SyncableEntity {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Project"
    static var defaultQuery = ProjectQuery()

    // A UUID issued by the backend and identical on every device.
    var id: UUID

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }

    @Property(title: "Name") var name: String
}

落とし穴は、デバイスごとに新しいローカル識別子を発行してしまうアプリ（オートインクリメントの行ID、インストールごとのUUID）です。そうした識別子はローカルでは一意でも、デバイス間では意味を持ちません。その場合のAppleの指針はこうです。プロトコルを採用し、実際に安定している値に同一性の鍵を置くこと。そうすればシステムはよりどころとなる耐久性のあるものを得られます。⁵ 同期は、各チームが自前のiCloud配管で手作業で解き続けてきた難問でした。SyncableEntityは、デバイス間の同一性の宣言を、Siriやシステムのほかの部分が働きかけられるフレームワークの中へと移します。

自己修復する検索：IndexedEntityQuery

iOS 16では、IndexedEntityのインスタンスをSpotlightにドネートして、個々のエンティティを検索可能にできました。欠けていたのは修復です。インデックスはずれたり、壊れたり、マイグレーション後に遅れたりします。iOS 27までは、システムに残された手立ては、アプリのCSSearchableIndexデリゲートやCSImportExtensionに頼ることだけでした。

IndexedEntityQueryは、システムがあなたの「クエリ」に再インデックスを求められるようにすることで、その隙間を埋めます。⁶

protocol IndexedEntityQuery : EntityQuery where Self.Entity : IndexedEntity

where句が前提条件です。クエリのエンティティはIndexedEntityに準拠していなければなりません。そもそもSpotlightにドネートするエンティティでなければ、再インデックスは意味をなさないからです。⁶ システムがアプリのインデックスに問題を検知すると、クエリ型がこれを採用していれば、このプロトコルのメソッドを呼び出します。採用していなければ、Spotlightは引き続きあなたのCSSearchableIndexオブジェクト（あるいは、その型にエンティティを関連付けてドネートしていた場合はCSImportExtension）に作業を求めます。⁶ あなたはメソッドを実装して、要求されたエンティティを取得し、好みの検索可能なインデックスを通じて再びドネートします。

import AppIntents
import CoreSpotlight

struct PhotoQuery: IndexedEntityQuery {
    func entities(for identifiers: [Photo.ID]) async throws -> [Photo] {
        try await library.photos(matching: identifiers)
    }

    func suggestedEntities() async throws -> [Photo] {
        try await library.recentPhotos(limit: 20)
    }

    // Called by the system during reindexing. Fetch the requested
    // entities and donate them again to Spotlight.
    func entities(matching string: String) async throws -> [Photo] {
        try await library.photos(matchingText: string)
    }
}

価値は運用面にあります。IndexedEntityQueryを正しく扱うアプリは、Spotlightの回復ループに加わります。システムがインデックスの誤りに気づき、アプリは求めに応じて新鮮なデータを供給します。次の全面的な再ドネートまでユーザーが静かに検索結果を失い続ける、ということがなくなるのです。クラスタのApp Intentsの基礎を扱った記事では、エントリを検索可能にするための素のIndexedEntityの露出を扱いました。IndexedEntityQueryは、その上に乗る保守の層です。

一つのパラメータ、複数の型：AppUnionValue

現実のインテントには、正当に複数の型のいずれかを取るパラメータが少なくありません。「これを共有」の「これ」が、写真か、ドキュメントか、リンクである、といった具合です。iOS 27以前の回避策は不格好でした。型ごとに別々のインテントを用意するか、文字列の判別子に加えてオプションのパラメータを並べる——しかしピッカーUIはそれをきれいに描画できませんでした。

iOS 27は、型付きのユニオンパラメータのためにAppUnionValueを加えます。⁷

protocol AppUnionValue : TypeDisplayRepresentable

このプロトコルに準拠したユニオン値は、豊富なメタデータを伴うShortcutsのパラメータとして機能します。これによりシステムは、メンバーとなる各型にわたって、ふさわしいピッカーと妥当なパラメータサマリーを提示できます。⁷ 準拠を手で書く必要はありません。@UnionValueマクロがそれを生成し、同じマクロが、AppUnionValueCasesProvidingに準拠する入れ子のCases列挙型も生成します。⁷⁸

protocol AppUnionValueCasesProviding : AppEnum

AppUnionValueCasesProvidingは、マクロが出力するCases列挙型によって自動的に準拠されます。⁸ これはcases列挙型をユニオン値型へと橋渡しし、AppEnum準拠を通じてメタデータを受け継ぎます。これが、ピッカー内で各ケースに表示名を与える仕組みです。⁸ 実際には、ユニオンを書いて注釈を付けます。

import AppIntents

@UnionValue
enum ShareTarget {
    case photo(PhotoEntity)
    case document(DocumentEntity)
    case link(URL)
}

struct ShareIntent: AppIntent {
    static var title: LocalizedStringResource = "Share Item"

    @Parameter(title: "Item")
    var target: ShareTarget

    func perform() async throws -> some IntentResult {
        // Switch over the concrete case and act accordingly.
        return .result()
    }
}

@UnionValueマクロがAppUnionValueとAppUnionValueCasesProvidingへの準拠を引き受けます。既定を超えるカスタムのメタデータが欲しい場合は、拡張でプロトコル要件を実装します。⁷ 一つのパラメータ、三つの妥当な型、そして三つすべてを表示する術を心得たピッカー。

所有権と効率

iOS 27の二つの異なる関心事が、本節を共有します。どちらも、システムがあなたのデータに対して不用意に振る舞うのを防ぐからです。すなわち、所有権を踏まえた確認と、一括処理の効率です。

破壊的なアクションを確認する：OwnershipProvidingEntity

アプリがエンティティをインテントに渡し、結果から返すと、Apple Intelligence、Siri、カスタムショートカットは、それらのエンティティをアプリをまたいで操作できます。破壊的または機微なアクション（エンティティの削除、共有されたものの更新）については、適切な文脈を伴う確認が欲しいところです。OwnershipProvidingEntityがそれを供給します。⁹

protocol OwnershipProvidingEntity : AppEntity

エンティティをこれに準拠させると、共有された、あるいは公開されたエンティティに対してインテントが操作するとき、システムはダイアログに適切な文脈を添えて確認を促します。⁹ 所有権の状態そのものはEntityOwnershipの値であり、これはフラグベースの構造体です。単一の状態を指定することも、OptionSetで複数を組み合わせることもできます。¹⁰

import AppIntents

struct AlbumEntity: OwnershipProvidingEntity {
    static var typeDisplayRepresentation: TypeDisplayRepresentation = "Album"
    static var defaultQuery = AlbumQuery()

    var id: UUID
    var isSharedWithFamily: Bool
    var isPublished: Bool

    var displayRepresentation: DisplayRepresentation {
        DisplayRepresentation(title: "\(name)")
    }

    @Property(title: "Name") var name: String

    // Reflect how the user has shared this album so the system can
    // calibrate its confirmation dialog.
    var ownership: EntityOwnership {
        var state: EntityOwnership = []
        if isSharedWithFamily || isPublished {
            state = .shared
        }
        return state
    }
}

この仕組みが最も効いてくるのは、共有コンテンツを扱うアプリです。公開した、あるいは家族と共有した写真アルバムは、非公開のものより慎重な確認を生むべきです。OwnershipProvidingEntityは、そのどちらであるかをエンティティがシステムに伝える手段なのです。⁹

メモリを食わない一括処理：EntityCollection

エンティティの解決はただではありません。インテントが数百のエンティティをパラメータとして取るとき、パラメータ解決の最中にすべての識別子を完全なインスタンスへと解決させると、よくないタイミングで相応の時間とメモリを食いかねません。EntityCollectionがその対処です。¹¹

struct EntityCollection<Entity> where Entity : AppEntity

このコレクションは、最初は各エンティティの識別子だけを保持し、必要になったら後から完全なインスタンスを取得する選択肢を提供します。¹¹ 多くの識別子を抱えるときは変数の型として使い、インテントが大きな集合を操作するときはパラメータの型として使います。

import AppIntents

struct DisableNotificationsIntent: AppIntent {
    static var title: LocalizedStringResource = "Disable Notifications"

    // Hundreds of conversations resolve lazily, not all at once.
    @Parameter(title: "Conversations")
    var conversations: EntityCollection<ConversationEntity>

    func perform() async throws -> some IntentResult {
        return .result()
    }
}

数百のエンティティを抱えるパラメータでは、識別子ごとの解決を省くことで、ユーザーがアクションの開始を待っている、まさにそのときに時間とメモリを節約できます。¹¹

インテントがどこで動くか：RunSystemShortcutIntentとIntentExecutionTargets

iOS 27の小ぶりな追加が二つ、全体像を締めくくります。RunSystemShortcutIntentは、ウィジェット専用のインテントで、ウィジェットのボタンから別のアプリを起動したり、App Shortcut、カスタムショートカット、システムアクションを実行したりするために使います。¹²

struct RunSystemShortcutIntent

これはシステムショートカット用のイニシャライザでButtonを初期化し、そのボタンをウィジェットに配置するためだけに使います。その文脈の外では役に立つことは何もしません。¹² ユーザーがウィジェットを設定するときにボタンのアクションを選び、インテントは設定UIにシステムが必要とするメタデータを供給します。あなたのウィジェットにショートカットのアクションやパラメータ、実装へのアクセスを渡すわけではありません。選ばれたショートカットが入力を求める必要がある場合、システムはそれを実行するためにShortcutsアプリを開くことがあります。¹²

IntentExecutionTargetsは、Swiftパッケージやフレームワークを通じてインテントやエンティティをアプリ、ウィジェット拡張、App Intents拡張で共有し始めると浮かび上がる問いに答えます。どのプロセスがインテントを実行するのか、という問いです。¹³

struct IntentExecutionTargets

既定では、システムは利用可能な任意のターゲットを使ってインテントやエンティティクエリを実行します。¹³ IntentExecutionTargetsを使うと、それを制約できます。Appleの例はブラウザです。ブックマークの追加はアプリが表示されていなくても起こり得るのでApp Intents拡張で構いませんが、新しいタブを開くのはアプリが表示されているときにしか意味をなさず、アプリ自身のプロセスを要します。¹³ あなたが妥当なターゲットを宣言すれば、システムはその制約を守ります。

採用の道筋

すでにApp Intentsを搭載しているアプリは、iOS 27の機能を段階的に加えられます。どれもコアモデルを書き直すものではありません。

1. 最も遅いインテントを見つける。 ファイルI/O、同期、オンデバイス推論、大きなデータ処理を行うインテントは、いずれもLongRunningIntentの候補です。プロトコルを採用し、作業をperformBackgroundTask(options:operation:)へ移し、全体を通じてprogressを報告します。30秒超の実行時間と、無償のLive Activities進捗が手に入ります。²³
2. エンティティの識別子を点検する。 すでにデバイス間で安定している（サーバーのUUID、iCloudのレコード名）なら、該当エンティティをSyncableEntityに準拠させて出荷します。デバイスごとなら、まず同一性を直し、それから準拠させます。⁵
3. エンティティがIndexedEntityであるクエリにIndexedEntityQueryを加える。 これは純粋に追加的です。メソッドはシステムが再インデックスを必要とするときにのみ呼ばれ、インデックスのずれを通じて検索結果は正しく保たれます。⁶
4. @UnionValueで複数型のパラメータをまとめる。 別々のインテントや判別子文字列でユニオンを偽装していた箇所はどこでも、マクロが一つのきれいなパラメータを与えてくれます。⁷
5. 共有されるエンティティをOwnershipProvidingEntityで印付けし、大きな集合のパラメータをEntityCollectionに切り替える。 前者は確認の安全性を、後者は解決の性能を高めます。⁹¹¹

FAQ

LongRunningIntentはバックグラウンドでどれくらい実行できますか？

Appleが文書化しているのは、引き上げられる「下限」であって、固定の上限ではありません。システムは従来、バックグラウンドタスクに完了までおよそ30秒を与えてきました。LongRunningIntent（performBackgroundTask(options:operation:)を介して）は、その制限を課すプラットフォーム上で、標準の制限を超えてその時間枠を自動的に延長します。²³ 延長は条件付きです。ProgressReportingIntent準拠が提供するProgressを更新し続けなければならず、やめればシステムは延長を取り消してタスクを早めに終了できます。³ 進捗報告は、追加の実行時間の対価だと考えてください。

LongRunningIntentを使うには進捗を報告しなければなりませんか？

はい。LongRunningIntentはprotocol LongRunningIntent : ProgressReportingIntentとして宣言されているため、採用にはProgressReportingIntent準拠とそのProgressが必要です。² コンパイラを満たすことを越えて、定期的な進捗更新はバックグラウンド実行時間の延長を生かし続け、Live ActivitiesがperformBackgroundTaskから自動的に描画するタイトル、サブタイトル、進捗バーに値を供給します。³

SyncableEntityは実行時に実際に何を変えますか？

エンティティの識別子がユーザーのデバイス間で同一であることを宣言します。これにより、システムはそのオブジェクトをデバイスごとに別々のオブジェクトとしてではなく、どこでも一つのエンティティとして扱えます。⁵ Appleが挙げる具体的な能力は、Siriがそのエンティティに関する会話をあるデバイスから別のデバイスへ移せることです。識別子がすでにデバイス間で安定しているなら、ほかに何も変えずにプロトコルを採用できます。デバイスごとなら、まず同一性を安定した値に置き直します。⁵

システムはいつIndexedEntityQueryを呼び出しますか？

アプリのSpotlightインデックスに問題を検知し、なおかつあなたのクエリ型がIndexedEntityQueryを採用している（そのエンティティがIndexedEntityに準拠している）ときです。⁶ システムはこのプロトコルのメソッドを呼び出して、該当するエンティティを取得し、再びSpotlightへドネートさせます。クエリがプロトコルを採用していなければ、Spotlightは代わりにあなたのCSSearchableIndexオブジェクトに、あるいはその型を通じてドネートしていた場合はCSImportExtensionに求めるところまで戻ります。⁶

エンティティの素の配列ではなくEntityCollectionを使うのはなぜですか？

EntityCollection<Entity>は、まず各エンティティの識別子だけを保持し、必要なら後から完全なインスタンスを取得します。¹¹ インテントのパラメータとしては、パラメータ解決の最中にすべての識別子を完全なインスタンスへ解決させることを防ぎます。数百のエンティティを抱えるパラメータでは、これが、場合によっては決定的な瞬間に時間とメモリを節約します。¹¹ 素の[Entity]配列は、何もかもを先取りで解決してしまいます。

RunSystemShortcutIntentはウィジェットの外でも使えますか？

いいえ。ウィジェットに配置するためにシステムショートカット用のイニシャライザでButtonを初期化することだけを目的に存在し、ほかの文脈では何の機能も提供しません。¹² ウィジェットの設定UIにメタデータを提示し、ユーザーが選んだアクションを表しますが、あなたのウィジェットやアプリに、その背後にあるショートカットのアクションやパラメータ、実装へのアクセスを与えるわけではありません。¹²

Apple Ecosystemクラスタの全体像はこちらです。型付けされたApp Intents、iOS 26での追加、MCPツールに対するルーティングの問い、Foundation Models、新しいFoundation Modelsのツール呼び出し制御、ランタイムとツールのLLMの区別、三つの面、単一の信頼できる情報源パターン、アプリと並んで動くMCPサーバー、Live Activities、watchOSのランタイム、SwiftUIの内部、SwiftDataのスキーマ規律、Liquid Glassのパターン、マルチプラットフォーム出荷、プラットフォームマトリクス、Visionフレームワーク、@Observableの内部、プラットフォームとしてのアクセシビリティ。ハブはApple Ecosystemシリーズにあります。iOSとAIエージェントを組み合わせた、より広い文脈についてはiOSエージェント開発ガイドをご覧ください。

参考文献