1. アプリケーション・コンポーザを使用したアプリケーションの構成
  2. Oracle SaaS RESTサービスとの統合
機械翻訳について

Oracle SaaS RESTサービスとの統合

アプリケーションから同じアプリケーション・インスタンス内のADFベースのRESTエンドポイントへのRESTアウトバウンド・コールを実行できます。 これは、Groovyを使用してアクセスできない可能性のあるオブジェクトからデータをフェッチするためにアプリケーション間コールを実行する必要がある場合に役立ちます。

このトピックでは、同じアプリケーション・インスタンス内でADFベースのRESTエンドポイントをコールする様々な方法を示します。

このトピックでは、次の方法について学習します:

  1. 内部RESTエンドポイントのベースURLを登録します。

  2. 様々なオブジェクトに対して問合せを実行できるように、GroovyスクリプトでそのベースURLに付加します。

  3. URLパラメータを動的に渡します。

  4. クラウド・サービスに付属しているファインダを使用します。

  5. 追加パラメータを使用して、RESTエンドポイントを変更します。

  6. 問合せパラメータ呼出しを行います。

  7. POSTリクエストを作成して、新しい連絡先アドレスを作成します。

ベースURLの登録

RESTエンドポイントと統合するには、その変数を後でGroovyスクリプトに含めることができるように、アプリケーション・コンポーザで変数として登録する必要があります。 RESTエンドポイントを登録する場合、エンドポイント全体を指定する必要はありません。 かわりに、時間を節約するために、RESTエンドポイントが再使用可能になるように、ベースURLのみを登録できます。 その後、Groovyスクリプトで、残りのエンドポイントを指定できます。 たとえば、Groovyスクリプトでは、ベースURLを参照し、コンタクトまたはアカウントに関する情報を取得するためのコールを行うかどうかを指定できます。

次に例を示します。 この例では、ベースURLを登録します。 次の項では、GroovyスクリプトでベースURLを使用します。

まず、ベースURLを登録します:

  1. アプリケーション・コンポーザの共通設定で、「Webサービス」をクリックします。

  2. 「Webサービス参照の作成」アイコンをクリックします。

  3. REST、OKの順に選択します。

  4. この参照の変数名を入力します。 たとえば、GetObjectsです。

  5. 統合するRESTエンドポイントのベースURLを入力します。 たとえば: 

    https://<host:port>/crmCommonApi/resources/latest/##Object##

  6. Basic認証を使用します。 「基本認証を使用して起動」を選択します。

  7. 「資格証明キー」フィールドで、webサービスへのアクセスに使用できる秘密キーの名前を指定します。 このキー名は、ユーザー名とパスワードとともに資格証明ストアに格納されます。

  8. 次に、リソースに対してメソッドを選択および構成します。 リソース操作(GET、POSTなど)および関連するペイロード書式タイプ(JSON/XML)を登録できます。 登録された操作のみがGroovy式ビルダーに表示されます。 この例では、GETメソッドを構成します。

    フィールド

    値

    メソッド名

    GET

    書式

    JSON

    要求ペイロード

    スキーマURL

    応答ペイロード

    コード・サンプル

    コード・サンプル

    		 
    {
  "items" : [ ],
  "count" : 0,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "<host:port>/crmCommonApi/resources/11.1.12/T1_c",
    "name" : "T1_c",
    "kind" : "collection"
  } ]
}

最後に、GroovyスクリプトでベースURLを使用します。 方法については、次の項を参照してください。

ベースURLへの追加

ベースURLを登録した後、GroovyスクリプトでベースURLを参照し、RESTエンドポイントを操作して、統合するオブジェクトを指定できます。 たとえば、同じベースURLを参照して、担当者またはアカウントのいずれかを問い合せることができます。 これを行うには、URLにさらに付加して、統合するオブジェクトを指定します。

前の項の例を続けて、GroovyスクリプトのRESTエンドポイントを参照します。

def conn = adf.webServices.GETObjects
try{
  def Object = "contacts"
  def result = conn.GET(Object)
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Contacts:"+contacts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Output"+conn.httpErrorResponse)
}

同じベースURLを使用してアカウントを問い合せるには、次のGroovyスクリプトを使用します:

def conn = adf.webServices.GetObjects
try{
  def Object = "accounts"
  def accounts = conn.GET(Object)
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Accounts:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Output"+conn.httpErrorResponse)
}

Groovyでのパラメータの動的渡し

RESTエンドポイントと統合する場合は、パラメータを渡して問合せを絞り込むことができます。 たとえば、担当者の問合せ時に、特定のパーティIDの情報を取得できます。 これは、GroovyスクリプトでパーティIDを動的に渡すことで、パーティIDをハード・コーディングせずに実行できます。

Groovyのコール元の場所に基づいて、パラメータを動的に渡すことができます。 スクリプトのコール元のページには、使用できるコンテキストがあります。 たとえば、このページには、ログインしているユーザーや、ユーザーが表示している担当者レコードに関するコンテキストがあります。 URLを指定するときに、パーティIDをURLパラメータとして指定できます。

たとえば、連絡先住所情報を非正規化(連結)フォームに保持するカスタム属性を定義したとします。 連絡先情報をレガシー・システムのいずれかに同期するには、非正規化形式の住所が必要です。 このユースケースを実現するには、パラメータとしてパーティ番号を使用して、コンタクトAPIを問い合せて住所をフェッチします。

この場合、RESTエンドポイントは次のようになります:

https://<host:port>/crmCommonApi/resources/latest/contacts/##PartyNumber##/child/Address

Groovyスクリプトは次のようになります:

def ContactAddressAPI = adf.webServices.ContactAddressAPI
try
{
def contactAddress = ContactAddressAPI.GET("<PartyNumber>")
def address1 = contactAddress.items[0].Address1
def address2 = contactAddress.items[0].Address2
def city = contactAddress.items[0].City
def state = contactAddress.items[0].State
def country = contactAddress.items[0].Country
def postalCode = contactAddress.items[0].PostalCode

def denormalizedAddress = address1 + ", " + address2 + ", " + city + ", " + state + ", " + country + ", " + postalCode 
return denormalizedAddress //concatenated address

 }
  catch(Exception ex)
{
println(ContactAddressAPI.statusCode+""); //for diagnostic logging
println(ContactAddressAPI.httpErrorResponse+""); //for diagnostic logging
throw ex;
}

検索機能の使用

Groovyスクリプトでは、ファインダを使用してデータのコレクションを検索することで、取得するレコードを絞り込むことができます。 検索者はクラウド・サービスに事前定義されており、保存済検索と同様です。 スクリプトでは、ファインダ名を指定し、使用しているファインダに応じて対応するファインダ変数(ある場合)を含めます。

前述のように、PartyNumberをRESTエンドポイントURL自体に直接アタッチして、特定の連絡先を取得できます。 たとえば: 

https://<host:port>/crmCommonApi/resources/11.12.1.0/contacts/##PartyNumber##

または、スクリプトにファインダを使用します。 クラウド・サービス内の各オブジェクトは、一連のファインダとともに出荷されます。 たとえば、連絡先RESTエンドポイントで使用可能なファインダを次に示します:

  • ContactPartyNumberRF: パーティ番号で担当者を検索します。

  • MyContacts: 自分の連絡先から連絡先を検索します。

  • MyBusinessContacts: 自分のビジネス担当者から担当者を検索します。

  • MyFavoriteContacts: お気に入り担当者から担当者を検索します。

  • PrimaryKey: 指定した主キーを持つ担当者を検索します。

ファインダを使用する形式は次のとおりです:

?finder=<finderName>;<variableName>=<variableValue>,<variableName2>=<variableValue2>

ファインダの使用例を見てみましょう。 この例では、PrimaryKeyファインダを使用して、指定した主キーを持つコンタクトを検索します。 このファインダの変数は次のとおりです:

  • PartyId (整数)

    担当者のOracleレコードID。

  • PersonProfileId (整数)

    一意の連絡先識別子。

まず、エンドポイントを登録します:

  1. アプリケーション・コンポーザの共通設定で、「Webサービス」をクリックします。

  2. 「Webサービス参照の作成」アイコンをクリックします。

  3. REST、OKの順に選択します。

  4. この参照の変数名を入力します。 たとえば、Contact_Basicです。

  5. 統合するRESTエンドポイントのURLを入力します。 たとえば: 

    https://<host:port>/crmCommonApi/resources/latest/contacts

  6. セキュリティのために、Basic認証を使用します。 「基本認証を使用して起動」を選択します。

  7. 「資格証明キー」フィールドで、webサービスへのアクセスに使用できる秘密キーの名前を指定します。 このキー名は、ユーザー名とパスワードとともに資格証明ストアに格納されます。

  8. 次に、リソースに対してメソッドを選択および構成します。 リソース操作(GET、POSTなど)および関連するペイロード書式タイプ(JSON/XML)を登録できます。登録された操作のみがGroovy式ビルダーに表示されます。 この例では、GETメソッドを構成します。

    フィールド

    値

    メソッド名

    GET

    書式

    JSON

    要求ペイロード

    スキーマURL

    応答ペイロード

    コード・サンプル

    コード・サンプル

    		 
    {
  "items" : [ ],
  "count" : 0,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c",
    "name" : "T1_c",
    "kind" : "collection"
  } ]
}

エンドポイントを登録した後、エンドポイントを参照し、GroovyスクリプトでPrimaryKeyファインダを使用できます。 次の例では、コンタクトRESTエンドポイントへの単一コールでのファインダ、フィールド・パラメータおよび問合せパラメータの両方の使用を示しています。 (フィールド・パラメータと問合せパラメータの詳細は、次の2つの項を参照してください。) 

def conn = adf.webServices.Contact_Basic
try{
  //Using finder and field parameters
  def queryParams = ['finder':'PrimaryKey;PartyId=100000017340195','fields':'PartyId,PartyNumber']
  conn.dynamicQueryParams = queryParams
  def contacts = conn.GET()
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Contact after applying finder and field query parameters:"+contacts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

各オブジェクトで使用可能なファインダおよび対応するファインダ変数の詳細は、クラウド・サービスのREST APIドキュメントを参照してください。

その他のタイプのパラメータの受渡し

パラメータの受渡しまたはファインダの使用は、RESTエンドポイントを変更する2つの方法です。 REST APIでは、qおよびfieldsパラメータを使用してコレクション・リソースをフィルタできる問合せもサポートされています。

  • ?q

    この問合せパラメータは、where句を定義します。 指定された式を使用してリソース・コレクションを問い合せます。

    ?qパラメータを使用する形式は次のとおりです:

    ?q=expression1;expression2

    たとえば、特定の部門に属するNYのすべての担当者を取得する場合があります。

    ?q=Deptno>=10 and <= 30;Loc!=NY

  • ?fields

    このパラメータは、リソース属性をフィルタします。 指定された属性のみが返されます。つまり、属性が指定されていない場合、属性は返されません(リンクのみを取得する場合に便利です)。 このパラメータを使用して、このコールで取得するフィールドを指定します。

    ?fieldsパラメータを使用する形式は次のとおりです:

    ?fields=Attribute1,Attribute2

RESTコールにアタッチできる追加パラメータの詳細は、クラウド・サービスのREST APIドキュメントを参照してください。

問合せパラメータのコール

前述のパラメータを渡すだけでなく、問合せパラメータをコールすることもできます。

問合せパラメータを定義して直接渡すことができます。 または、ペイロードを定義してからペイロードを渡します。

たとえば、問合せパラメータ自体を定義します。 レスポンス・メソッドはGETです。 

def queryParam = [OpptyId:'6756253']
OpptyDC.dynamicQueryParams = queryParam
def response = adf.webservices.OpptyDC.GET()

または、ペイロードを定義してRESTエンドポイントに追加します。 これは、レコードを作成または更新する場合に特に便利です。 次の例のレスポンス・メソッドはPOSTです。 

def requestPayload = [OpptyName:'GreenServerTech', Account:'Pinnacle', Owner:'Lisa.Jones']
def response = adf.webservices.OpptyDC.Post(requestPayload)

特定の勘定科目レコードの問合せパラメータを定義する例を見てみましょう。 この例では、問合せパラメータを定義し、qパラメータも渡します。

まず、エンドポイントを登録します:

  1. アプリケーション・コンポーザの共通設定で、「Webサービス」をクリックします。

  2. 「Webサービス参照の作成」アイコンをクリックします。

  3. REST、OKの順に選択します。

  4. この参照の変数名を入力します。 たとえば、GetAccountUsingSAMLです。

  5. 統合するRESTエンドポイントのURLを入力します。 たとえば: 

    https://<host:port>/crmCommonApi/resources/latest/accounts

  6. セキュリティのために、Secure Socket Layer (SSL)認証スキームを介したSecurity Assertion Markup Language (SAML)を使用します。 「SAML over SSLを使用したユーザー・アイデンティティの伝播」を選択します。

  7. 次に、リソースに対してメソッドを選択および構成します。 リソース操作(GET、POSTなど)および関連するペイロード書式タイプ(JSON/XML)を登録できます。登録された操作のみがGroovy式ビルダーに表示されます。 この例では、GETメソッドを構成します。

    フィールド

    値

    メソッド名

    GET

    書式

    JSON

    要求ペイロード

    スキーマURL

    応答ペイロード

    コード・サンプル

    コード・サンプル

    		 
    {
  "items" : [ ],
  "count" : 0,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c",
    "name" : "T1_c",
    "kind" : "collection"
  } ]
}

エンドポイントを登録した後、エンドポイントを参照し、この例では、Groovyスクリプトの問合せパラメータとqパラメータの両方を渡します。

def conn = adf.webServices.GetAccountUsingSAML
try{
  // Provide query parameter for the account object you want to receive 
  def queryParams = ['q':'PartyId=300100010638186']
  conn.dynamicQueryParams = queryParams
  def accounts = conn.GET()
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

POSTリクエストの作成

URLを使用して、RESTリソースに対してGET、POST、PATCH、DELETEなどの標準メソッドを実行できます。 この項では、POSTリクエストを確認します。

POSTリクエストを使用して、リソースに新しいアイテムを作成します。 リクエスト・コンテンツ・タイプは次のとおりです: 

application/vnd.oracle.adf.resourceitem+json

2つのPOSTリクエストを見てみましょう。 まず、エンドポイントを登録します:

  1. アプリケーション・コンポーザの共通設定で、「Webサービス」をクリックします。

  2. 「Webサービス参照の作成」アイコンをクリックします。

  3. REST、OKの順に選択します。

  4. この参照の変数名を入力します。 たとえば、Account_SAMLです。

  5. 統合するRESTエンドポイントのURLを入力します。 たとえば: 

    https://<host:port>/crmCommonApi/resources/latest/accounts

  6. セキュリティのために、SAML over SSL認証スキームを使用します。 「SAML over SSLを使用したユーザー・アイデンティティの伝播」を選択します。

  7. 次に、リソースに対してメソッドを選択および構成します。 リソース操作(GET、POSTなど)および関連するペイロード書式タイプ(JSON/XML)を登録できます。登録された操作のみがGroovy式ビルダーに表示されます。 この例では、POSTメソッドを構成します。

    フィールド

    値

    メソッド名

    POST

    書式

    JSON

    要求ペイロード

    コード・サンプル

    コード・サンプル

    {"OrganizationName":"M1"}

    応答ペイロード

    コード・サンプル

    コード・サンプル

    		 
    {
  "items" : [ ],
  "count" : 0,
  "hasMore" : false,
  "limit" : 25,
  "offset" : 0,
  "links" : [ {
    "rel" : "self",
    "href" : "http://<host:port>/crmCommonApi/resources/11.1.12/T1_c",
    "name" : "T1_c",
    "kind" : "collection"
  } ]
}

次の2つの例では、前に登録したRESTエンドポイントを使用して新しい連絡先アドレスを作成するPOSTリクエストを作成します。 どちらの例も、GroovyスクリプトでHTTPヘッダーを設定する方法を示します。

  1. POSTリクエストでHTTPリクエスト・ヘッダーのコンテンツ・タイプを設定します。

    def conn = adf.webServices.Account_SAML
try{
  // Create new Account object by passing Organization name
  // Set Content-Type request header 
  def OrganizationName =[OrganizationName:'TestOrganization1']
  def httpHeaders=['Content-Type':'application/vnd.oracle.adf.resourceitem+json']
  conn.requestHTTPHeaders=httpHeaders
  def accounts = conn.POST(OrganizationName)
  
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

  2. POSTリクエストでHTTPレスポンス・ヘッダーのコンテンツ・タイプを設定します。

    def conn = adf.webServices.Account_SAML
try{
  // Create new Account object by passing Organization name
  // Set Content-Type request header 
  def OrganizationName =[OrganizationName:'TestOrganization2']
  def httpHeaders=['Content-Type':'application/vnd.oracle.adf.resourceitem+json']
  conn.requestHTTPHeaders=httpHeaders
  def accounts = conn.POST(OrganizationName)
  
  println("Headers:"+conn.responseHTTPHeaders)
  // Retrieve Content-Type from response headers
  println("Content-Type:"+conn.responseHTTPHeaders['Content-Type'])
  println("Status:"+conn.statusCode)
  println("Account:"+accounts)

}catch(Exception e){
  println("Headers:"+conn.responseHTTPHeaders)
  println("Status:"+conn.statusCode)
  println("Error:"+e)
}

関連トピック