Oracle Fusion Cloud Customer ExperienceのSales and Fusion ServiceのREST API

重複する組織および個人の識別

Fusion Data Qualityのサブスクリプションを使用すると、顧客データ管理で対話型重複識別を有効にして、顧客登録の既存のレコードの重複である可能性がある新規顧客レコードの作成を回避できます。この機能を使用すると、新規顧客レコードを保存しようとすると、重複の可能性があるレコードがアプリケーションから通知され、既存のレコードを使用するのではなく、新規レコードの作成を続行することを選択できます。また、Fusion Data Qualityサービスでは、モバイル・アプリケーションや顧客レコードを作成するためのOracle Visual Builder webインタフェースなど、カスタム・クライアントに対して同様の重複識別フローを開発する場合、REST APIを使用した対話型重複識別もサポートされます。このセクションは、REST APIの機能、実装および使用状況の理解に役立ちます。

前提条件

Fusion Data Quality重複識別REST関数には、Oracle Fusionデータ品質サービス・オプションとともにOracle CX Salesサービス・ベースのサブスクリプションが必要です。必要なサブスクリプションがアクティブになると、実装では、エンタープライズ・データ品質照合構成の管理設定タスクを使用して、組織および個人のデータ品質照合構成を構成およびアクティブ化する必要があります。このタスクの詳細は、CX Salesヘルプ・センターの『CX Sales and Fusion Service向け顧客データ管理の実装』ガイドを参照してください。

RESTデータ品質照合の概要

RESTベースの重複識別は、組織オブジェクトおよび個人オブジェクトで使用でき、標準のCX Sales RESTリソースの特殊な処理を介して提供されます。 CX Sales組織および個人RESTリソースの詳細は、CX Salesヘルプ・センターの『CX Sales and Fusion Service向けREST API』ガイドを参照してください。

URLの例

このリソースURL形式を使用します。

POST

crmRestAPI/resouces/11.13.18.05/<hubOrganizations|hubPersons>/

次の各項では、組織および個人重複識別APIとその特殊なサブリソースの詳細を説明します。

重複組織の識別

組織のRESTベースの重複識別は、'findDuplicates'という組織のCX Sales REST APIの特殊な処理を介して提供されます。

URLの例

USeこのURL形式。

POST

crmRestAPI/resouces/11.13.18.05/hubOrganizations/action/findDuplicates

リクエストの本文には、タイプが"hubOrganization"のフラット・マップ構造が含まれ、属性名が組織RESTオブジェクトの最上位レベル・スキーマに準拠している必要があります。属性名: match valueマップには、アプリケーション・コンポーザで作成されたサービス対応のカスタム属性を含めることができます。

APIの一致動作は、組織オブジェクトのアクティブなデータ品質照合構成に従って、リアルタイム一致構成パラメータ設定によって制御されます。次の設定によって制御されます:

照合しきい値スコア
クラスタ・キー・モード
標準スコアリング・ルールとカスタム・スコアリング・ルールのどちらを使用するか

レスポンスの本文は、構成された照合設定ごとの照合基準を満たすCX Sales顧客登録の組織レコードのリストと、リクエストで発行された照合属性/値ペアで構成されます。リストの各要素は、組織の識別子、よく使用される属性値、照合スコアを駆動するスコアリング・ルールと属性値を提供するフラット・マップ構造です。

hubOrganizationレスポンス・スキーマは次のとおりです:

PartyId
PartyNumber
OrganizationName
FormattedAddress
FormattedPhoneNumber
RawPhoneNumber
Url
EmailAddress
PrimaryContactPartyId
PrimaryContactPartyNumber
CreationDate
LastUpdateDate
LastUpdatedBy
CreatedBy
MatchScore
MatchRule
MatchedAttributes

例

例1: 重複の可能性がある成功したリクエスト

リクエスト本文の例

次に、JSON形式のリクエスト本文の例を示します。

{
"hubOrganization":
 {
 "OrganizationName": "Merrrill Technologies",
 "AddressLine1": "500 South Drive",
 "PostalCode": "94035",	
 "State": "CA",
 "Country":"US"
 }
}

レスポンス本文の例

JSON形式のレスポンス本文の例を次に示します。

{ 
"result": 
 [ 
 {
 "PartyId":"300100193515606",   
 "PartyNumber": "CDRM_970814",  
 "OrganizationName": "Merrill Technologies", 
 "FormattedAddress": "500 South Drive,MOFFETT FIELD, CA 94035", 
 "FormattedPhoneNumber": null,    
 "RawPhoneNumber": null,  
 "Url": null,    
 "EmailAddress": null, 
 "PrimaryContactPartyId":null,   
 "PrimaryContactPartyNumber": null,   
 "PrimaryContactPartyName":null,      
 "CreationDate":"2019-09-23 07:57:37.263",   
 "LastUpdateDate": "2019-09-23 08:01:11.364", 
 "LastUpdatedBy": "SALES_ADMIN",   
 "CreatedBy": "SALES_ADMIN",
 "MatchScore": "77",    
 "MatchRule": "[E125C] Full name all words shorter with typos; premise; no subpremise; postal code starts with",   
 "MatchedAttributes": "PostalCode,AddressLine1,Country,OrganizationName"  
 }  
 ] 
}

例2: 重複の可能性がある識別がない成功したリクエスト

リクエスト本文の例

次に、JSON形式のリクエスト本文の例を示します。

{
 "hubOrganization": 
 {
 "OrganizationName": "Merrrill Technologies"
 }
}

レスポンス本文の例

次に、JSON形式のレスポンス本文の例を示します。

{
  "result": []
}

例3: リクエスト本文にカスタム属性を持つ成功したリクエスト

リクエスト本文の例

次に、JSON形式のリクエスト本文の例を示します。

{
  "hubOrganization": 
   { 
   "OrganizationName": "Merrill Technologies",
   "OrganizationDEO_NonVerifiedVAT_c": "A5678" 
   }
 }

レスポンス本文の例

JSON形式のレスポンス本文の例を次に示します。

{ 
 "result": 
 [  
 { 
  "PartyId": "300100180759704", 
  "PartyNumber": "CDRM_859821",  
  "OrganizationName": "Merrill Technologies", 
  "FormattedAddress": "500 South Drive,MOFFETT FIELD, CA 94035",
  "FormattedPhoneNumber": null,    

"RawPhoneNumber": null, 
  "Url": null,     
  "EmailAddress": null,   
  "PrimaryContactPartyId": null,   
  "PrimaryContactPartyNumber": null,  
  "PrimaryContactPartyName": null,
  "CreationDate": "2019-09-26 21:54:26.208", 
  "LastUpdateDate": "2019-10-01 05:32:56.461",    
  "LastUpdatedBy": "SALES_ADMIN",   
  "CreatedBy": "swatson",    
  "MatchScore": "89", 
  "MatchRule": "[E020H] Full name exact; VAT number", 
  "MatchedAttributes": "OrganizationDEO_NonVerifiedVAT_c,OrganizationName"   
 }  
 ] 
 }

重複する個人の識別

個人のRESTベースの重複識別は、'findDuplicates'という個人のCX Sales REST APIの特殊な処理を介して提供されます。

URLの例

このリソースURL形式を使用します。

POST

crmRestAPI/resouces/11.13.18.05/hubPersons/action/findDuplicates

リクエストの本文には、タイプが"hubPerson"のフラット・マップ構造が含まれ、属性名がhubPersons RESTオブジェクトの最上位レベル・スキーマに準拠している必要があります。属性名: match valueマップには、アプリケーション・コンポーザで作成されたサービス対応のカスタム属性を含めることができます。

APIの一致動作は、コンタクト・オブジェクトのアクティブなデータ品質照合構成に従って、リアルタイム一致構成パラメータ設定によって制御されます。次の設定によって制御されます:

照合しきい値スコア
クラスタ・キー・モード
標準スコアリング・ルールとカスタム・スコアリング・ルールのどちらを使用するか

レスポンスの本文は、構成された照合設定ごとの照合基準を満たすCX Sales顧客登録の個人レコードのリストと、リクエストで発行された照合属性/値ペアで構成されます。リストの各要素はフラット・マップ構造で、個人の識別子、個人に対して一般的に使用される属性値、照合スコアを駆動するスコアリング・ルールを提供します。担当者レスポンス・スキーマは次のとおりです:

PartyId
PartyNumber
FirstName
LastName
MiddleName
FormattedAddress
RawHomePhoneNumber
FormattedHomePhoneNumber
RawWorkPhoneNumber
FormattedWorkPhoneNumber
RawMobileNumber
FormattedMobileNumber
EmailAddress
OrganizationPartyId
OrganizationPartyNumber
OrganizationPartyName
LastUpdateDate
LastUpdatedBy
CreatedBy
CreationDate
MatchScore
MatchRule
MatchedAttributes

例

例1: 重複の可能性がある成功したリクエスト

リクエスト本文の例

次に、JSON形式のリクエスト本文の例を示します。

{
  "hubPerson":  
  {  
 "FirstName":"Arnold",  
 "LastName": "Smith"
 "EmailAddress": "Arnold.smith@email.abc",
 "Address1":"318 Elm St",
 "PostalCode": "53421" 
  }  
}

レスポンス本文の例

JSON形式のレスポンス本文の例を次に示します。

{
    "result": [
        {
            "PartyId": "300100544978841",
            "PartyNumber": "CDRM_935497",
            "FirstName": "Arnold",
            "LastName": "Smith",
            "MiddleName": null,
            "FormattedAddress": "319 Elm St,Anytown,53421",
            "RawHomePhoneNumber": null,
            "FormattedHomePhoneNumber": null,
            "RawWorkPhoneNumber": null,
            "FormattedWorkPhoneNumber": null,
            "RawMobileNumber": null,
            "FormattedMobileNumber": null,
            "EmailAddress": "Arnold.smith@email.abc",
            "OrganizationPartyId": null,
            "OrganizationPartyNumber": null,
            "OrganizationPartyName": null,
            "LastUpdateDate": "2021-02-25 19:35:23.52",
            "LastUpdatedBy": "SALES_ADMIN",
            "CreatedBy": "SALES_ADMIN",
            "CreationDate": "2021-02-25 19:35:18.003",
            "MatchScore": "100",
            "MatchRule": "[I020B] Name exact; address; e-mail",
            "MatchedAttributes": "FirstName,LastName,Address1,EmailAddress"
        }]}

ヒントおよび考慮事項

findDuplicatesアクションは、ベースhubOrganizationsおよびhubPersons RESTリソースでサポートされている同じレコード・タイプの重複候補を返します。
「findDuplicates」処理によって返される一致する組織または個人のリストは、照合スコアの降順にソートされます。
レスポンスに含まれる一致候補の最大数は、デフォルトの推奨値の20ですが、ORA_ZCQ_MAX_CANDIDATESプロファイル・オプションで構成できます。
hubOrganizationおよびhubPersonの"findDuplicates"アクションには、ベースhubOrganizationsおよびhubPersons RESTリソース・エンドポイントへのアクセスに必要なロールや権限以外の追加のロールや権限は必要ありません。
findDuplicatesリクエスト本文には、最上位レベルのhubOrganizationまたはhubPersonリソース・スキーマの属性のみを含めることができます。子コレクションの照合属性は現在サポートされていません。
findDuplicatesアクションは、カスタム・クライアントが顧客データ管理パーティ・センター・インタフェースによって提供される対話型の重複識別フローをレプリケートできるように設計されています。
findDuplicates機能は、Oracle CXの顧客マスター・リングの一部であり、候補者の識別およびスコアリング・プロセスを満たすのに十分な情報を含む予測可能なデータ・シェイプと連携できます。顧客レコードの一般的な検索インタフェースとなることを意図していません。
"findDuplicates"レスポンスは、成功したリクエストに対して200のHTTPレスポンス・ステータス・コードを返します:
- リクエスト本文に少なくとも1つの正しい属性マッピングがあるかぎり、サービスは誤って指定された一致属性を無視
- 成功したレスポンスには、ゼロ個以上の一致を指定できます

レスポンスには、次に示すほとんどのエラー条件のHTTPレスポンス・ステータス・コード400が含まれます:
- リクエスト本文に正しく指定された一致属性が含まれていません
  - "一致の識別時にデータ品質サービスでエラーが発生しました\
必要な引用符、カンマまたは中カッコの欠落など、リクエストの構造が無効です
- "指定されたペイロードを解析できません\
データ品質照合サービスが有効化されていないか、アクティブな構成がありません
- データ品質照合サーバーが無効になっているため、クレンジング操作を実行できませんでした。ヘルプ・デスクに連絡してください。」。

サービス対応のカスタム属性の正しい名前を識別するには、hubOrganizationまたはhubPerson RESTエンドポイントの???describe???レスポンスを参照してください
- 標準属性でカスタム属性名プリフィクス・パターンを使用しないでください
- hubPersonsオブジェクトのdescribeは、https://<server>>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/hubPersons/describeから読み取ることができます
- hubOrganizationオブジェクトのdescribeは、https://<server>>.oraclecloud.com/crmRestAPI/resouces/11.13.18.05/hubOrganizations/describeから読み取ることができます