SOAP Webサービスを介したOracle Sales Cloudデータへのアクセス

10 SOAP Webサービスを介したOracle Sales Cloudデータへのアクセス

Oracle Sales Cloudの拡張機能および統合を構築する場合、Oracle Sales Cloudによって公開されたSOAP Webサービスを介して標準オブジェクト・データおよびカスタム・オブジェクト・データにアクセスできます。

通常、各標準オブジェクトには特定のSOAP Webサービスが関連付けられています。たとえば、OpportunityService Web サービスは、商談オブジェクトにアクセスするための操作を提供します。ただし、カスタム・オブジェクトのデータには、対象のアプリケーション・コンテナに応じて汎用Webサービスを介してアクセスできます。

WebインタフェースでOracle Sales Cloudを検出および検索するには、開発者接続機能を使用できます。または、Oracle Sales Cloudインスタンスに組み込まれているサービス・カタログ・サービスと呼ばれる、組込み済みのSOAP Webサービスを使用して、他のSOAP Webサービスをプログラムで検索することもできます。

Oracle Sales Cloud SOAP Webサービスを使用する前に、アクセスを確立するために必要なセキュリティ要件を理解するだけでなく、使用するWebサービスとともに、対応する操作や予想されるペイロード構造も特定する必要があります。

トピック

開発者接続について

Oracle Sales Cloudでは、標準オブジェクトとカスタム・オブジェクト用のSOAP Webサービスのコレクションが公開されています。Oracle Sales Cloud開発者接続を使用して、Oracle Sales Cloud内で使用可能なSOAP Webサービスを探索できます。

注意:

Oracle Sales Cloud開発者接続を使用する前に、アカウントに次のロール権限の少なくとも1つがあることを確認してください。

FND_INTEGRATION_SPECIALIST_JOB、 FND_APPLICATION_DEVELOPER_JOB
ZCA_CUSTOMER_RELATIONSHIP_MANAGEMENT_APPLICATION_ADMINISTRATOR_JOB

また、管理者は、ATK_WEB_SERVICE_INFO_ACCESS_PRIV権限をカスタム・ロールに付与してから、アクセスを必要とするユーザーにこのカスタム・ロールを付与できます。「CloudでのOracle Sales Cloudの保護」の「Sales Cloudのユーザーおよびロールのプロビジョニング」を参照してください。

開発者接続では、4つの列(「名前」、「ビジネス・オブジェクト」、「ライフ・サイクル」および「WSDL」)を含む表ビュー内にすべてのSOAP Webサービスがリストされます。

列名	説明
名前	SOAP Webサービス名が表示されます。この列をクリックすると、エンドポイントのURL、WSDL、セキュリティ・ポリシー、サポートされている操作、ペイロードなどのWebサービスに関する情報を取得できます。「Oracle Applications Cloud用のCloud SOAP Webサービス」の「開発者接続の使用」を参照してください。
ビジネス・オブジェクト	Webサービスが属するビジネス・オブジェクト・サービスを示します。Oracle Sales Cloudビジネス・オブジェクトの完全な文書については、「Oracle Sales Cloud用のCloud SOAP Webサービス」の「ビジネス・オブジェクト・サービス」を参照してください。
ライフ・サイクル	サービスがアクティブと非推奨のどちらであるかを示します。
WSDL	WebサービスのWSDLファイルに対するアイコン・リンクがあります。

Oracle Sales Cloud開発者接続を使用したSOAP Webサービスの検索

開発者接続を使用することにより、公開されているすべてのOracle Sales Cloud SOAP Webサービスを検索できます。

開発者接続を使用してSOAP Webサービスを検索する手順:

Oracle Sales Cloudにログインします。
「ナビゲータ」メニューをクリックします。
「ツール」列の下、またはツール列が表示されていない場合は「詳細」→「ツール」の下にある「開発者接続」をクリックします。
「Webサービス」の下で、ドロップダウンからすべてのWebサービスを選択します。また、フィルタで「アクティブなWebサービス」を選択したり、特定のSOAP Webサービスを検索したりすることもできます。たとえば、「Opportunity」を検索するときに検索アイコンをクリックすると、OpportunityおよびOpportunity Configurationサービスが表示されます。
「同期」ボタンをクリックし、すべてのSOAP Webサービスが含まれるリストのロードを開始します。このリスト内で、任意のサービス名をクリックすると、特定のSOAP Webサービスに関する詳細を取得できます。

サービス・カタログ・サービスを使用したSOAP Webサービスの検索

サービス・カタログ・サービスは、他のSOAP Webサービスを起動する上で必要なデータをプログラムで検出および取得するために使用できるOracle Sales Cloud SOAP Webサービスです。

サービス・カタログ・サービスを使用して、パブリック外部サービスのエンドポイントおよびメタデータ情報を取得できます。

サービス・カタログ・サービスのエンドポイントを取得する手順:

Oracle Sales Cloudにログインします。
「ナビゲータ」メニューをクリックします。
「設定と保守」をクリックします。
右側の「タスク」フライアウト・メニューを展開します。このメニューは、ページ・アイコンによって表されます。次に、トポロジのレビューをクリックします。

注意:
トポロジのレビューにアクセスするには、ジョブにASM_REVIEW_TOPOLOGY_HIERARCHY_PRIV権限がある必要があります。ユーザー・アカウントに必要なロールがない場合、トポロジ情報にアクセスすることはできません。セキュリティ管理者に連絡してください。
「詳細」タブを開きます。展開可能なアイテムのリストが表示されます。下にスクロールし、CommonDomainを検索してから、矢印アイコンをクリックして展開します。
下にスクロールし、アプリケーション・コア設定を展開し、fndAppCoreServicesエンドポイントを見つけます。サーバー・インスタンスおよびサーバー・ポートが外部表サーバー・ホストおよび外部表サーバー・ポート列にリストされます。
次の例に示すように、外部表サーバー・ホスト、外部表サーバー・ポートおよびfndAppCoreServices/ServiceCatalogService?WSDL を追加することにより、サービス・カタログ・サービスのURLを導出します。

https://<crm_server:PortNumber>/fndAppCoreServices/ServiceCatalogService?wsdl

<crm_server:PortNumber> は、それぞれ外部表サーバー・ホストおよび外部表サーバー・ポートです。

Webサービス操作およびペイロード構造について

開発者接続を使用して、Oracle Sales Cloud SOAP Webサービスの操作や、サポートされているリクエスト・ペイロードおよびレスポンス・ペイロードに関する情報をレビューできます。

「開発者接続」内のWebサービス名の下をクリックすることにより、Webサービスの追加詳細を取得できます。これにより、名前、ビジネス・オブジェクト、ライフ・サイクルの各ステータス(アクティブまたは非推奨)、エンドポイントURL、WSDLファイル、セキュリティ・ポリシーおよび説明を含むWebサービスに関する情報が含まれる「Webサービスのサマリー」タブが開きます。

Webサービス操作にアクセスするには、「操作」タブ(2番目のタブ)をクリックします。このタブには、たとえば、すべてのアクティビティ・サービス操作を表示するための操作など、サポートされているすべてのWebサービス操作がリストされます。

図developer_connect_operations_tab.pngの説明

操作をクリックすると、その操作に関する詳細が表示されます。たとえば、(アクティビティWebサービスから) createActivityをクリックすると、そのエンドポイントのペイロードを示すウィンドウ・オーバーレイが開きます。

payloads_overlay.pngの説明が続きます
図payloads_overlay.pngの説明

標準オブジェクトのWebサービスの操作およびペイロード構造

標準オブジェクトのWebサービスには、複数の作成、読取り、更新および削除(CRUD)操作が用意されています。各操作には、リクエストおよびペイロード・スキーマが定義されています。

標準オブジェクトのWebサービスには、次の作成、読取り、更新および削除操作が用意されています。

createObject (createOpportunityやcreateLocationなど)
deleteObject
getObject
findObject
updateObject
mergeObject
processObject
processCSObject

次のサンプルは、事業所ビジネス・オブジェクトのcreateLocationリクエストのペイロードを示しています。

 <soap:Body> <ns1:createLocation xmlns:ns1= "http://xmlns.oracle.com/apps/cdm/foundation/parties/ locationService/applicationModule/types/"> <ns1:location xmlns:ns2= "http://xmlns.oracle.com/apps/cdm/foundation/parties/locationService/"> <ns2:Address1>1 Oracle Parkway</ns2:Address1> <ns2:City>Redwood Shores</ns2:City> <ns2:State>CA</ns2:State> <ns2:Country>US</ns2:Country> <ns2:PostalCode>94065</ns2:PostalCode> <ns2:CreatedByModule>AMS</ns2:CreatedByModule> </ns1:location> </ns1:createLocation> </soap:Body>

次のペイロードは、前のリクエストに対するレスポンスです。

 <ns2:result...> <ns1:Value> <ns1:LocationId>300100039119119</ns1:LocationId> ...<ns1:Country>US</ns1:Country> <ns1:Address1>1 Oracle Parkway</ns1:Address1> <ns1:Address2 xsi:nil="true"/> <ns1:Address3 xsi:nil="true"/> <ns1:Address4 xsi:nil="true"/> <ns1:City>Redwood Shores</ns1:City> <ns1:PostalCode>94065</ns1:PostalCode> <ns1:State>CA</ns1:State> <ns1:Province xsi:nil="true"/> <ns1:County xsi:nil="true"/> ...</ns1:Value> </ns2:result>

createObject、deleteObjectおよびgetObject操作は、説明なしに内容を理解できます。次の表は、他の操作を説明しており、ほとんどの操作について、動作に関する注意事項を示しています。

操作	使用するタイミング	注意
`updateObject`	レコードを更新するとき。	存在しないレコードを更新すると、例外が発生します。
`findObject`	Oracle Sales Cloud UIの場合と同じように、検索条件を定義することによって特定のレコードを検索するとき。レスポンス・ペイロードを制御するために使用します。	IDフィールドのみに対する検索が可能である`getObject`操作とは対照的に、オブジェクト内の任意のフィールドに対する検索が可能です。レスポンス・ペイロードを制御可能であるため、この操作は、Webサービスのパフォーマンスを改善する上で役に立ちます。使用例については、「Oracle Sales Cloud用のCloud SOAP Webサービス」の「find操作の例」を参照してください。
`mergeObject`	レコードが存在しない場合にレコードを作成するか、レコードが存在する場合にレコードを更新する必要があるとき。既存のレコードに対して新しい子または子孫オブジェクト・エンティティを作成する必要があるとき。	レコードが存在する場合にレコードを更新し、レコードが存在しない場合にレコードを作成することを意味するアップサートを実行します。このアップサート動作はすべてのレベルで行われます。たとえば、既存の最上位レベルのエンティティに子エンティティを追加する場合、マージ操作を使用する必要があります。最上位エンティティで定義されている作成および更新操作を使用することはできません。
`processObject`	レコードのリストに対して作成、更新、削除またはマージ操作を実行するとき。オブジェクトが大きいか、レスポンス・ペイロードが必要ない場合に使用します。一括処理用として使用します。	ペイロード内の値を制御する機能を使用すると、パフォーマンスを最適化しやすくなります。
`processCSObject`	様々なオブジェクトに対して様々な操作が適用されている場合に作成、更新または削除操作を実行するとき。	親オブジェクトを削除せずに子オブジェクトを削除できます。たとえば、オーダー親オブジェクトを削除せずにオーダー明細子オブジェクトを削除できます。

nilおよび欠落値について

スキーマ内の一部フィールドは、nillableフィールドとしてマークされています。作成および更新操作での欠落、値なしおよびnilフィールドの場合、次のルールが適用されます。

作成操作のルール: オブジェクトのフィールドの要素がペイロードに含まれていない場合、デフォルト値が使用されます(存在する場合)。フィールドが含まれているが、値(<fieldName/>や<fieldName></fieldName>など)がない場合、またはフィールドにnil値(<fieldName xsi:nil="true">など)がある場合、次のルールの1つが適用されます。
- フィールドがnillableである場合、値はnil値として処理されます。
- フィールドがnillableでない場合、値はnilとして処理され、無効です。

更新操作のルール: オブジェクトのフィールドの要素がペイロードに含まれていない場合、フィールド値は更新されません。フィールドが含まれているが、値(<fieldName/>や<fieldName></fieldName>など)がない場合、次のルールの1つが適用されます。
- フィールドがnillableである場合、値は更新されません。
- フィールドがnillableでない場合、値はnilとして処理され、無効です。
フィールドにnil値(<<fieldName xsi:nil="true">など)がある場合、次のルールの1つが適用されます。
- フィールドがnillableである場合、フィールド値はnilに更新されます。
- フィールドがnillableでない場合、値はnilとして処理され、無効です。

「Oracle Sales Cloud用のCloud SOAP Webサービス」の「ビジネス・オブジェクト・サービスの操作」を参照してください。

カスタム・オブジェクトのWebサービスの操作およびペイロード構造

カスタム・ビジネス・オブジェクトのWebサービスは、汎用であり、オブジェクトの構造は定義しません。カスタム・オブジェクトの構造はオブジェクトごとに異なり、要素タイプが最も制限の少ないタイプです。このため、アクセス対象のオブジェクトに合わせてリクエスト・メッセージおよびレスポンス・メッセージを成形できます。

カスタム・オブジェクトのWebサービスには、次の操作が用意されています。

createEntity
deleteEntity
getEntity
findEntity
updateEntity
mergeEntity
processEntity

最も一般的に使用されるタイプは、string、anyTypeおよびkeyValueです。keyValueは、<ns-ref:api-name>value</ns-ref:api-name>という形式の要素です。要素の用途に応じて、API名は、オブジェクトまたはそのフィールドの1つを表します。

リクエストを構築したり、レスポンスを解釈したりするには、カスタム・オブジェクトのAPI名を把握する必要があるとともに、フィールド・タイプおよび必要なフィールドを把握する必要があります。この情報を探し出すには、アプリケーション・コンポーザでカスタム・オブジェクトにアクセスします。

内部オブジェクト名: この名前は、オブジェクトの削除時に表示されるウィンドウであるオブジェクトの「概要」ウィンドウの「名前」フィールドに表示されます。通常、内部カスタム・オブジェクト名は、オブジェクト名に接尾辞_c (カスタム(custom)を表す略称)を付けたものです。
フィールド: オブジェクトを展開し、「フィールド」を選択し、フィールドとそのフィールド・タイプのリスト、および必要なフィールドを表示します。
内部フィールド名: 内部名を表示するには、「フィールド」ページから、フィールドを選択してから、「編集」アイコンをクリックします。「API名」フィールドに内部名が表示されます。通常、内部カスタム・フィールド名は、フィールド名に接尾辞_cを付けたものです。

メッセージの例

次のペイロードは、見積カスタム・オブジェクトのcreateEntityリクエスト用です。

<S:Body> <ns5:createEntity ...> <ns5:object xsi:type="ns6:Quote_c" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"> <ns6:RecordName>EQ1</ns6:RecordName> <ns6:QuoteId_c>1</ns6:QuoteId_c> <ns6:QuoteNr_c>1</ns6:QuoteNr_c> <ns6:Description_c>SimpleQuote</ns6:Description_c> <ns6:Status_c>Open</ns6:Status_c> <ns6:Opportunity_Id_Opty2Quote>300000001038150</ns6:Opportunity_Id_Opty2Quote> </ns5:object> <ns5:objectName>Quote_c</ns5:objectName> </ns5:createEntity> </S:Body>

次のペイロードは、前のリクエストに対するレスポンスです。

 <env:Body> <ns0:createEntityResponse xmlns:ns0="http://xmlns.oracle.com/apps/sales/custExtn/extnService/types/"> <ns2:result xsi:type="ns1:Quote_c" ...> <ns1:Id>300000001038356</ns1:Id> <ns1:RecordName>000002</ns1:RecordName> ...<ns1:QuoteId_c>1</ns1:QuoteId_c> <ns1:QuoteNr_c>1</ns1:QuoteNr_c> <ns1:Description_c>SimpleQuote</ns1:Description_c> <ns1:Status_c>Open</ns1:Status_c> <ns1:Revenue_c xsi:nil="true"/> <ns1:Revenue_cCurrencyCode>USD</ns1:Revenue_cCurrencyCode> <ns1:Revenue_cCurcyConvRate>1</ns1:Revenue_cCurcyConvRate> <ns1:Primary_c>true</ns1:Primary_c> <ns1:Opportunity_Id_Opty2Quote>300000001038150</ns1:Opportunity_Id_Opty2Quote> </ns2:result> </ns0:createEntityResponse> </env:Body>

セキュアなWeb Serviceアクセスについて

クライアント・アプリケーションからWebサービスを起動する場合は常に、Webサービスのセキュリティ・ポリシーに対応するクライアント・ポリシーをアタッチする必要があります。Oracle Sales Cloud Webサービスは、Oracle Web Services Manager (OWSM)のwss11_saml_or_username_token_over_ssl_service_policyサービス・ポリシーを使用して保護されます。

wss11_saml_or_username_token_over_ssl_service_policyサービス・ポリシーと互換性のあるクライアント・セキュリティ・ポリシーの詳細は、「Oracle Sales Cloud SOAP Webサービスのセキュリティの理解」を参照してください。

HTTPアナライザを使用したOracle Sales Cloud Webサービス・リクエストのテスト

Webサービスのテスト・ツールは、プランニング・ステージ中にWebサービスにアクセスする際に役に立ちます。また、テスト・ツールは、検索リクエストを構成する際にも役に立ちます。HTTPアナライザのテスト・ツールを使用して、オブジェクトに対して正しいWebサービスを使用しているかどうかを確認できます。

Webサービスのテスト・ツールの例には、ここで説明するHTTPアナライザ、およびhttp://www.soapui.orgから入手できるSoapUIがあります。

Webサービスをテストするには、WSDLのURLを把握する必要があります。このURLは、サービス・エンドポイントにWebサービスのパスを加えたものです(https://myserver:myport/opptyMgmtExtensibility/SalesCustomObjectService?WSDLなど)。

HTTPアナライザを使用してOracle Sales Cloud Webサービス・リクエストをテストする手順:

Oracle JDeveloperの「ツール」から、「HTTPアナライザ」を選択します。
IDEの下部にあるログ領域で「HTTPアナライザ」タブが開きます。
「HTTPアナライザ」タブで、ツールバーに表示される「新規リクエストの作成」アイコンをクリックします。
エディタ領域で「HTTPアナライザ: 未送信メッセージ」タブが開きます。
「WSDLを開く」をクリックし、WSDLのURLを入力してから、「OK」をクリックします。
IDEによってWSDLがフェッチおよび分析されてから、SOAP構造が表示されます。
最上部の近くの「操作」リストから、テストする操作を選択します。
「SOAP構造」リージョンの下の「HTTPコンテンツ」タブをクリックしてから、リクエスト・メッセージを入力します。
Oracle Sales Cloudにアクセスするためのユーザー名およびパスワードを指定するには、次の手順を実行します。
1. 「SOAP構造」タブをクリックしてから、上部の「リクエストHTTPヘッダー」を展開します。
2. 緑色のプラス・アイコンの横の下矢印をクリックしてから、認可基本を選択します。
3. 「認可」行の「値」列で、次の図に示すように、usernameを自分のユーザー名に置き換えてから、passwordを自分のパスワードに置き換えます。この例では、ユーザー名とパスワードがmyusernameとmypasswordに置き換えられています。
  
  図request-http-headers-section.pngの説明
4. [Tab]キーを押し、ユーザー名とパスワードをエンコードします。
  値がエンコードされていない場合、リクエストは失敗します。
下部の「リクエストの送信」ボタンをクリックします。
リクエストが送信されてから、右側のセクションにレスポンスが表示されます。レスポンスをXML形式で表示するには、「HTTPコンテンツ」タブをクリックします。

注意:

WS-Securityヘッダーに移入し、ユーザー名とパスワードの値を渡すこともできます。WS-Securityヘッダーに移入する場合、タイムスタンプ・ヘッダーも忘れずに移入してください。

トラブルシューティング:

問題	解決策
HTTP基本認証を使用する場合、401未認可エラーが発生します。	ユーザー名とパスワードが正しいかどうかを確認します。
HTTP基本認証を使用する場合、500内部サーバー・エラーが発生します。	エンドポイントが正しいかどうかを確認します。
WS-Securityの使用時に、500内部サーバー・エラーが発生し、「FailedAuthentication: The security token cannot be authenticated」というメッセージが表示されます。	ユーザー名とパスワードが正しいかどうかを確認します。
WS-Securityの使用時に、500内部サーバー・エラーが発生し、「InvalidSecurityToken : The security token is not valid」というメッセージが表示されます。	WS-Securityのタイムスタンプ・ヘッダーを含めたかどうかを確認します。