SOAP API 開発者ガイド
jAPI コールの基礎
API コールとは、クライアントアプリケーションがタスク実行のために実行時に起動できる特定の操作のことです。コールには次のようなものがあります。
- 組織内のデータのクエリ。
- データの追加、更新、削除。
- データのメタデータの取得。
- 管理タスク実行のためのユーティリティの起動。
開発環境を使用し、標準 Web サービスプロトコルを使用してプログラムで次の操作を実行する Web サービスクライアントアプリケーションを作成できます。
- ログインサーバにログインし (login())、後続のコールで使用する認証情報を受け取る
- 組織の情報に対するクエリを実行する (query()、queryAll()、queryMore()、および retrieve() コール)
- 組織の情報に対するテキスト検索を実行する (search() コール)
- データを作成、更新、および削除する (create()、merge()、update()、upsert()、delete()、および undelete() コール)
- ユーザ情報の取得 (getUserInfo() コール)、パスワードの変更 (setPassword() および resetPassword() コール)、システム時間の取得 (getServerTimestamp() コール) などの管理タスクを実行する
- データをローカルに複製する (getDeleted() および getUpdated() コール)
- 組織データについてのメタデータを取得およびアクセスする (describeGlobal()、describeSObject()、describeSObjects()、describeLayout()、および describeTabs() コール)
- 承認プロセスを使用する (process())
- 組織からカテゴリグループとカテゴリを返す (describeDataCategoryGroups() および describeDataCategoryGroupStructures())。
各コールについての完全な詳細は、「基本となる API コール」、「記述用の API コール (describe)」、および「ユーティリティ API コール」を参照してください。
API コールの特徴
すべての API コールには次の特徴があります。
- サービス要求とレスポンス — 使用しているクライアントアプリケーションはサービス要求を準備し、Lightning プラットフォーム Web サービスに API 経由で送信します。Lightning プラットフォーム Web サービスは要求を処理してレスポンスを返し、クライアントアプリケーションが応答を処理します。
- 同期 — API コールが起動されると、クライアントアプリケーションはサービスからレスポンスを受け取るまで待機します。非同期コールはサポートしていません。
-
自動コミットとエラー時のロールバック — デフォルトで、Salesforce オブジェクトに書き込みを行うすべての操作は自動的にコミットされます。これは、SQL の AUTOCOMMMIT 設定と類似しています。オブジェクトの複数のレコードへの書き込みを試みる create()、update()、および delete() コールでは、各レコードの書き込み操作はそれぞれ別のトランザクションとして扱われます。たとえば、クライアントアプリケーションが新しい取引先を 2 つ作成する場合、グループとしてではなく、完全に独立した挿入処理で作成され、それぞれ個別に成功または失敗と判断されます。
API バージョン 20.0 以降では、AllOrNoneHeader ヘッダーが追加され、すべてのレコードが正常に処理されない限り、コールですべての変更をロールバックできるようになりました。このヘッダーは、create()、delete()、undelete()、update()、および upsert() コールでサポートされます。
データアクセスに影響する要素
API を使用する際、次の要素は組織データへのアクセスに影響を与えます。
- アクセス
- 組織で API アクセスが有効になっている必要があります。
- オブジェクトは、Salesforce に連絡してアクセスを要求するまで使用できない場合があります。たとえば、エンタープライズテリトリー管理がアプリケーションで有効になっている場合にのみ Territory2 を表示できます。オブジェクトのアクセスに関する情報は、各オブジェクトの「使用方法」セクションに記述されます。
- 場合によっては、機能に関連するオブジェクトに API でアクセスできるようにするには、機能を 1 回は使用する必要があります。たとえば、recordTypeIds を使用できるのは、ユーザインターフェースで組織に少なくとも 1 つのレコードタイプが組織に作成された後です。
-
データアクセスの問題を調査するには、最初に WSDL を調査します。
- Enterprise WSDL: 生成された Enterprise WSDL ファイルには、組織で利用可能なすべてのオブジェクトが含まれています。API を使用して、クライアントアプリケーションは Enterprise WSDL ファイルで定義されているオブジェクトにアクセスできます。
- Partner WSDL: 生成された Partner WSDL ファイルを使用する際、クライアントアプリケーションは describeGlobal() コールで返されたオブジェクトにアクセスできます。
- オブジェクトレベルおよび項目レベルのセキュリティ
- API はユーザインターフェースで設定したオブジェクトレベルおよび項目レベルのセキュリティを優先します。ログインユーザの権限およびアクセス設定で許可されている場合のみ、オブジェクトや項目にアクセスできます。たとえば、ユーザに表示されない項目は、query() または describeSObjects() コールでも返されません。同様に、参照のみ項目は更新できません。
- ユーザ権限
- API へのアクセスを試みるユーザは、「API 対応」権限が選択されている必要があります。デフォルトでは選択されています。
- クライアントアプリケーションは、ログインユーザと呼ばれるユーザとしてログインします。ログインユーザの権限によって、組織の特定のオブジェクトおよび項目への次のようなアクセスが許可または拒否されます。
- 参照 — ユーザは、このタイプのオブジェクトを参照のみできます。
- 作成 — ユーザは、このタイプのオブジェクトを参照し、作成できます。
- 編集 — ユーザは、このタイプのオブジェクトを参照し、更新できます。
- 削除 — ユーザは、このタイプのオブジェクトを参照し、編集、削除できます。
- 共有
- ほとんどの API コールでは、ログインユーザの共有モデル外のデータは返されません。アプリケーションの場合と同様に、ユーザには、組織のデフォルトと手動によるレコード共有の指定のうち、最も権限の大きいアクセス権が付与されます。
- 共有を無効にするユーザ権限
-
- すべて表示 — ユーザは共有設定に関係なく、このオブジェクトに関連付けられたすべてのレコードを表示できます。
- すべて変更 — ユーザは共有設定に関係なく、このオブジェクトに関連付けられたすべてのレコードの参照、編集、削除、移行、承認を実行できます。
- すべてのデータの編集 — ユーザは共有設定に関係なく、すべてのレコードの参照、編集、削除、移行、承認を実行できます。この権限は、「すべて表示」および「すべて変更」と異なり、オブジェクトレベルの権限ではありません。
- 関連オブジェクト
- オブジェクトによっては、他のオブジェクトに権限を依存する場合があります。たとえば、AccountTeamMember は、共有の権限は Account レコードなど、権限が割り当てられている関連オブジェクトに従います。同様に、Partner は関連する取引先の権限に依存します。
- あるレコードの所有者を変更しても、他の関連レコードには自動的にカスケードされません。たとえば、Account の所有者が変更された場合、その Account に関連付けられた Contract の所有者が自動的に変更されることはありません。クライアントアプリケーションでそれぞれの所有者を別個に、明示的に変更する必要があります。
- オブジェクトプロパティ
- create() コールでオブジェクトを作成する場合、オブジェクトの createable 属性を true に設定する必要があります。オブジェクトで許可されている操作を判断するために、クライアントアプリケーションでオブジェクトに対して describeSObjects() コールを実行し、DescribeSObjectResult のプロパティを調べることができます。
- ページレイアウトとレコードタイプ
- ページレイアウトとレコードタイプについて Salesforce ユーザインターフェースで定義した要件は、API では適用されません。
- 特定の項目が必須であるかどうかはページレイアウトで指定できますが、API は、そのようなレイアウト固有の項目制限や入力規則を create() および update() コールで適用しません。制限を適用するかどうかはクライアントアプリケーションが決定します。
- 指定されたレコードで選択する選択リスト値や、異なるプロファイルを持つユーザが参照するページレイアウトは、レコード型で制御できます。ただし、ユーザインターフェースで設定され、適用されるルールは API では適用されません。たとえば、API は、選択リスト項目の値がログインユーザのプロファイルに関連付けられたレコードタイプ制限で許可されるかどうかを確認しません。同様に、ログインユーザのプロファイルに関連付けられたレイアウトに項目がないという理由で、クライアントアプリケーションが特定の項目にデータを追加するのを API で拒否することはありません。
- 参照整合性
- 参照整合性を確保するために、API は特定の動作を適用または防止します。
- reference 項目の ID 値は create() および update() コールで検証されます。
- クライアントアプリケーションがレコードを削除した場合、その子の ChildRelationship の cascadeDelete プロパティの値が true であれば、その子もコールの一部として自動的に削除されます。たとえば、クライアントアプリケーションが Opportunity を削除すると、関連付けられた OpportunityLineItem レコードもまた削除されます。ただし、OpportunityLineItem が削除できない、または使用中の場合、親の Opportunity の削除は失敗します。 たとえば、クライアントアプリケーションが Invoice_Statement を削除すると、関連付けられた Line_Item レコードも削除されます。ただし、Line_Item が削除できない、または使用中の場合、親の Invoice_Statement の削除は失敗します。何が削除されるかを確認するには、DescribeSObjectResult を使用し、ChildRelationship 値を確認します。
cascadeDelete の実行を阻止するいくつかの例外があります。たとえば、取引先にケースが関連付けられている場合、他のユーザが所有する関連商談がある場合、または関連付けられた取引先責任者がカスタマーポータルで有効になっている場合、その取引先は削除できません。さらに、現在のユーザによる成立した商談がある場合、または有効な契約のある場合、レコードの削除要求は失敗します。