※本記事は2025年10月13日に米国で公開された Named Query API Simplifies Data Access for Agents and Apps の抄訳です。本記事の正式言語は英語であり、その内容および解釈については英語が優先されます。
注意：この記事の内容は、Winter ’26リリースで提供される名前付きクエリAPI（ベータ版）の最新情報にもとづき改訂されています。
名前付きクエリAPIは、Salesforceが正式公開に向けて準備している新機能です。このAPIは、システム管理者や開発者がAIエージェントやアプリをSalesforce組織内のデータにアクセスさせたいときに、そのプロセスを簡略化するのに役立ちます。名前付きクエリAPIを利用すれば、AIエージェントのカスタムエージェントアクションの土台になるSOQLクエリを定義し、それを外部アプリケーションから利用可能なREST APIとして公開することができます。
このブログ記事では、名前付きクエリAPIを使ってシンプルなデータアクセスを実現する方法を詳しく見ていきます。名前付きクエリAPIを作成する方法から、APIカタログでの表示を確認する方法、REST APIとして呼び出す方法、名前付きクエリAPIのREST APIを記述したOpenAPIドキュメントをダウンロードする方法、名前付きクエリAPIからエージェントアクションを作成する方法、作成したアクションをAIエージェントに組み込む方法まで、順を追って説明します。
現在のAIエージェントやアプリのデータアクセスの仕組み
現在、AIエージェントやアプリをSalesforce組織内のデータにアクセスさせるには、いくつかの方法があります。
AIエージェントの場合は、次のとおりです。
- AIエージェントにアクセスさせたいデータを返す「レコードを取得」要素を含んだフローを作成し、このフローからカスタムエージェントアクションを作成する
- もしくは、AIエージェントにアクセスさせたいデータを返すSOQLクエリを含んだApexクラスを作成し、このクラスを呼び出し可能なメソッドとして公開したうえで、このメソッドからカスタムエージェントアクションを作成する
- こうして作成したカスタムエージェントアクションを、AIエージェントに実行させる
以上のようなやり方でAIエージェントをデータにアクセスさせることは可能ですが、フローやApexクラスを作成する手間がかかります。名前付きクエリを利用すれば、話はもっとシンプルになります。
アプリケーションの場合は、次のとおりです。
- REST APIの/queryを利用して、必要なデータを返すSOQLクエリをSalesforce組織に送信する（ただしこの方法では、SOQLの知識が必要）
- もしくは、sObjects REST APIを利用し、レコードIDを通じて目的のレコードを取得する（ただしこの方法では、フィルタリング条件に合致するレコードセットを取得することはできない）
名前付きクエリAPIを利用すれば、RESTのセマンティクスを使って必要なデータをアプリケーションに引き渡す専用のREST APIを公開できます。
名前付きクエリAPIを作成、管理する
まず、AIエージェントやアプリケーションにアクセスさせたいデータを公開する名前付きクエリAPIを作成します。名前付きクエリAPIの作成は［設定（Setup）］で行います。ツリーの［インテグレーション（Integrations）］で［名前付きクエリAPI（Named Query API）］を選択すると、名前付きクエリAPIのリストが表示されます。
［新規の名前付きクエリAPI（New Named Query API）］ボタンをクリックすると、名前付きクエリAPIの新規作成画面が開きます。
クエリのフィルタリング条件を定義したい場合は、WHERE句にパラメーターを指定します。上の例のように、パラメーター名の前にはコロンを付けてください。これらの入力パラメーターは、呼び出し元のAIエージェントやアプリケーションから名前付きクエリAPIへと引き渡されます。
ベータ版の名前付きクエリAPIでは、WHERE句とLIMIT句で入力パラメーターがサポートされています。
名前付きクエリAPIをVisual Studio Code内で作成する
コーディングでの実装を好む場合は、Visual Studio Code内で名前付きクエリAPIを作成し、そのメタデータをSalesforce組織にデプロイすることも可能です。
たとえば、以下のGetAccountDetails.apiNamedQuery-meta.xmlファイルは、名前付きクエリAPIを表すメタデータを定義しています。このメタデータをSalesforce組織にデプロイすれば、名前付きクエリAPIが作成され、［設定（Setup）］で管理できるようになります。
1Name of this account
2Name name
365.0
4SELECT Id, Name, NumberOfEmployees FROM Account WHERE Name = :name
5 Get id, name, and annual revenue from Account entity filtered by name
6Get Account Details名前付きクエリAPIがAPIカタログ上にあることを確認する
名前付きクエリAPIを保存すると、自動的にAPIカタログに表示されるようになります。
このリスト内のいずれかの名前付きクエリAPIを選択すると、詳細情報を確認できます。
名前付きクエリAPIを使ってカスタムエージェントアクションを作成するには、その名前付きクエリAPIをエージェントアクション向けに有効化する必要があります。この有効化は、APIカタログ内で行います。APIカタログを見れば、どの名前付きクエリAPIが有効化されているかがわかります。エージェントアクション向けに有効化された名前付きクエリAPIは、［設定（Setup）］での編集や削除はできなくなります。編集や削除をするには、先にAPIカタログ内で無効化する必要があります。無効化する前に、そのAPIを使用中のエージェントアクションがないことを確認しましょう。
注意 – 名前付きクエリAPIをREST APIとして使う場合は、この有効化は必要ありません。
名前付きクエリAPIをREST APIとして呼び出す
名前付きクエリAPIを保存すると、自動的にREST APIとして公開されます。先ほど例に挙げた名前付きクエリAPIは、以下のようなREST APIとして公開されることになります。
<my domain>/services/data/v65.0/named/query/AccountFromName?name=xxxx
名前付きクエリAPI内で定義した入力パラメーターは、REST API上ではクエリパラメーターとして公開され、外部アプリケーションから簡単に入力を渡せる仕組みになっています。なお、このAPIリクエストを実行するユーザーには、クエリ先のエンティティに対する読み取りアクセス権限が必要です。
先ほどの名前付きクエリAPIを呼び出し、nameパラメーターの値として「Urban Eats Collective」を渡すREST API呼び出しは、以下のようになります。
<my domain>/services/data/v65.0/named/query/AccountFromName?name=Urban%20Eats%20Collective
この呼び出しに対し、名前付きクエリAPIは、「Urban Eats Collective」アカウントの詳細情報を返します。
1{
2 "totalSize": 1,
3 "done": true,
4 "records": [
5 {
6 "attributes": {
7 "type": "Account",
8 "url": "/services/data/v65.0/sobjects/Account/001Ws00003cPDMRIA4"
9 },
10 "Name": "Urban Eats Collective",
11 "Description": "A trendy, fast-casual dining group offering an eclectic mix of globally inspired dishes. Known for its vibrant, urban ambiance and innovative menu, Urban Eats Collective brings city vibes to every meal.",
12 "Phone": "214-555-1010",
13 "Website": "www.urbaneats.com",
14 "NumberOfEmployees": 500,
15 "BillingAddress": {
16 "city": "Dallas",
17 "country": "USA",
18 "geocodeAccuracy": null,
19 "latitude": null,
20 "longitude": null,
21 "postalCode": "75219",
22 "state": "TX",
23 "street": "2401 Victory Avenue"
24 }
25 }
26 ]
27}OpenAPIドキュメントをダウンロードする
ご利用のSalesforce組織でREST API OpenAPIのベータ版が有効になっている場合は、名前付きクエリAPIを公開しているREST APIについてのOpenAPIドキュメントをダウンロードできます。ご利用のSalesforce組織でREST API OpenAPIのベータ版を有効化する方法については、こちらのドキュメント（英語）をご覧ください。
たとえば「AccountFromName」という名前付きクエリAPIのOpenAPIドキュメントを生成するには、以下のREST API呼び出しを使用します。
1/services/data/v65.0/async/specifications/oas3
2{
3 "resources" : ["/named/query/AccountFromName"]
4}名前付きクエリAPIからエージェントアクションを作成する
名前付きクエリAPIを保存し、APIカタログ内で有効化すると、その名前付きクエリAPIからエージェントアクションを作成できるようになります。新規アクションの作成は、［設定（Setup）］の［Agentforceアセットライブラリー（Agentforce Asset Library）］画面の［新規のエージェントアクション（New Agent Action）］から行います。
名前付きクエリAPIをAIエージェント内で使う
最後に、作成したエージェントアクションをトピックに追加し、そのトピックをAIエージェントに登録します。これで、AIエージェントが名前付きクエリAPIを通じてSalesforce組織内のデータにアクセスし、ユーザーのリクエストに対応できるようになります。
なお、このAIエージェントを使って名前付きクエリAPIを呼び出すユーザーには、クエリ対象オブジェクトへの読み取りアクセス権限が必要です。
まとめ
この記事では、名前付きクエリAPIを利用して、AIエージェントやアプリケーションからSalesforce組織内のデータへのアクセスを他の方法よりシンプルに実現する方法について説明しました。
AIエージェントがエージェントアクションを通じてデータにアクセスする方式ならば、SOQLクエリを専用のUI内で記述するだけでよく、フローを作成したりApexクラスを記述したりする必要はありません。アプリケーションの場合も、名前付きクエリAPIを利用することで、RESTのセマンティクスを使って必要なデータをアプリケーションに引き渡す専用のREST APIを簡単に実現できます。
名前付きクエリAPIのベータ版は、10月にWinter ’26リリースの一部として提供予定です。名前付きクエリAPIの利用に興味をお持ちの方は、「名前付きクエリAPIからアクションを作成する（ベータ版）」（英語）のページをご覧ください。ご利用のSalesforce組織内で名前付きクエリAPIを有効化する方法も、こちらのページに書かれています。
このベータ版の機能についての感想や、名前付きクエリAPIを実際のAIエージェントやAPIにどう利用できるかのアイデアなど、皆様からのフィードバックをお待ちしています。いただいたご意見は、正式リリースの参考にさせていただきます。ベータ版に関するご意見やご質問は、Salesforce IntegrationのTrailblazer Communityにご投稿ください。また、名前付きクエリAPIの活用事例をご紹介いただける方はお声がけください。TrailblazerDXやDreamforceでの共同プレゼンテーションをお願いできればと思います。
その他のリソース
- ドキュメント – 名前付きクエリAPIからアクションを作成する（ベータ版）（英語）
ドキュメント – sObjects REST APIのOpenAPI 3.0ドキュメントを生成する（ベータ版）（英語）
オリジナルの執筆者について
Jeremy Westerman
Salesforce APIのプロダクトマネジメント担当ディレクター。Salesforce Platform上のデータにアクセスするSalesforce APIのプロダクト責任者。LinkedInアカウントはこちら。
