實體端點(設定檔存取)
Adobe Experience Platform可讓您使用RESTful API或使用者介面存取Real-Time Customer Profile資料。 本指南會概述如何使用API存取實體(通常稱為「設定檔」)。 如需使用Experience Platform UI存取設定檔的詳細資訊,請參閱設定檔使用手冊。
快速入門
本指南中使用的API端點是Real-Time Customer Profile API的一部分。 繼續之前,請先檢閱快速入門手冊,以取得相關檔案的連結、閱讀本檔案中範例API呼叫的手冊,以及有關成功呼叫任何Experience Platform API所需必要標題的重要資訊。
實體解析度
作為架構升級的一部分,Adobe引入帳戶和機會的實體解決方案,使用根據最新資料的確定性ID比對。 實體解析工作會在批次細分期間每日執行,然後再評估具有B2B屬性的多實體對象。
此增強功能可讓Experience Platform識別並統一代表相同實體的多個記錄,進而改善資料一致性,並啟用更準確的受眾細分。
以前,「帳戶」和「機會」依賴身分圖表式的解析,此解析會連結身分,包括所有歷史擷取。 在新的實體解析方法中,身分僅會根據最新資料連結
實體解析如何運作?
- 在 之前:若使用資料通用編號系統(DUNS)編號做為額外身分識別,且帳戶的DUNS編號已在來源系統(如CRM)中更新,則帳戶ID會連結到舊和新的DUNS編號。
- 在 之後:如果將DUNS號碼當做其他身分識別使用,且帳戶的DUNS號碼已在來源系統(如CRM)中更新,則帳戶ID只會連結到新的DUNS號碼,因此能更準確地反映帳戶的目前狀態。
更新後,Profile Access API現在會在實體解析作業週期完成後反映最新的合併設定檔檢視。 此外,一致的資料提供分段、啟用和分析等使用案例,並改善資料準確性和一致性。
擷取實體 retrieve-entity
您可以透過向/access/entities
端點發出GET請求以及所需的查詢引數來擷取設定檔實體。
API格式
code language-http |
---|
|
請求路徑中提供的查詢引數會指定要存取的資料。 您可以包含多個引數,以&分隔。
若要存取設定檔實體,您 必須 提供下列查詢引數:
schema.name
:實體的XDM結構描述的名稱。 在此使用案例中,schema.name=_xdm.context.profile
。entityId
:您嘗試擷取的實體識別碼。entityIdNS
:您嘗試擷取的實體的名稱空間。 如果entityId
是 而非 XID,則必須提供此值。
附錄的查詢引數區段中提供了有效引數的完整清單。
要求
以下請求會使用身分來擷取客戶的電子郵件和名稱。
accordion | ||
---|---|---|
使用身分擷取實體的範例要求 | ||
|
回應
成功的回應會傳回HTTP狀態200和要求的實體。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
note note |
---|
NOTE |
如果相關圖表連結超過50個身分,此服務將傳回HTTP狀態422和「太多相關身分」訊息。 如果收到此錯誤,請考慮新增更多查詢引數來縮小搜尋範圍。 |
API格式
code language-http |
---|
|
請求路徑中提供的查詢引數會指定要存取的資料。 您可以包含多個引數,以&分隔。
若要存取B2B帳戶資料,您 必須 提供下列查詢引數:
schema.name
:實體的XDM結構描述的名稱。 在此使用案例中,這個值為schema.name=_xdm.context.account
。entityId
:您嘗試擷取的實體識別碼。entityIdNS
:您嘗試擷取的實體的名稱空間。 如果entityId
是 而非 XID,則必須提供此值。
附錄的查詢引數區段中提供了有效引數的完整清單。
要求
accordion | ||
---|---|---|
擷取B2B帳戶的範例要求 | ||
|
回應
成功的回應會傳回HTTP狀態200和要求的實體。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
API格式
code language-http |
---|
|
請求路徑中提供的查詢引數會指定要存取的資料。 您可以包含多個引數,以&分隔。
若要存取B2B機會實體,您 必須 提供下列查詢引數:
schema.name
:實體的XDM結構描述的名稱。 在此使用案例中,schema.name=_xdm.context.opportunity
。entityId
:您嘗試擷取的實體識別碼。entityIdNS
:您嘗試擷取的實體的名稱空間。 如果entityId
是 而非 XID,則必須提供此值。
附錄的查詢引數區段中提供了有效引數的完整清單。
要求
accordion | ||
---|---|---|
擷取B2B機會實體的範例要求 | ||
|
回應
成功的回應會傳回HTTP狀態200和要求的實體。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
擷取多個實體 retrieve-entities
您可以對/access/entities
端點發出POST要求,並在承載中提供身分,以擷取多個設定檔實體。
API格式
code language-http |
---|
|
要求
以下請求會根據身分清單擷取多個客戶的名稱和電子郵件地址。
accordion | |||||||||||||||||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
擷取多個實體的範例請求 | |||||||||||||||||||||||||||||||||||
|
回應
成功的回應會傳回HTTP狀態200,並在要求內文中指定實體的要求欄位。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
API格式
code language-http |
---|
|
要求
以下請求會擷取請求的B2B帳戶。
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
擷取多個實體的範例請求 | ||||||||||||||||||||
|
回應
成功的回應會傳回HTTP狀態200以及請求的實體。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
API格式
code language-http |
---|
|
要求
以下請求會擷取請求的B2B商機。
accordion | ||||||||||||||||||||
---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
擷取多個實體的範例請求 | ||||||||||||||||||||
|
回應
成功的回應會傳回HTTP狀態200以及請求的實體。
accordion | ||
---|---|---|
包含請求實體的範例回應 | ||
|
存取後續結果頁面
擷取時間序列事件時,結果會分頁。 如果有後續結果頁面,_page.next
屬性將包含ID。 此外,_links.next.href
屬性提供要求URI以擷取下一頁。 若要擷取結果,請對/access/entities
端點提出另一個GET要求,並使用提供的URI值取代/entities
。
/entities/
。 它應該只會出現一次,例如/access/entities?start=...
API格式
GET /access/{NEXT_URI}
{NEXT_URI}
_links.next.href
。要求
下列要求會使用_links.next.href
URI做為要求路徑,以擷取結果的下一頁。
code language-shell |
---|
|
回應
成功的回應會傳回結果的下一頁。 此回應沒有後續結果頁面,如_page.next
和_links.next.href
的空字串值所指示。
code language-json |
---|
|
刪除實體 delete-entity
- 帳戶
- 帳戶 — 個人關係
- 機會
- 機會 — 個人關係
- Campaign
- 促銷活動會員
- 行銷清單
- 行銷清單成員
您可以透過向/access/entities
端點發出DELETE請求以及所需的查詢引數,從設定檔存放區中刪除實體。
API格式
DELETE /access/entities?{QUERY_PARAMETERS}
請求路徑中提供的查詢引數會指定要存取的資料。 您可以包含多個引數,以&分隔。
若要刪除實體,您 必須 提供下列查詢引數:
schema.name
:實體的XDM結構描述的名稱。 在此使用案例中,您只能 使用schema.name=_xdm.context.profile
。entityId
:您嘗試擷取的實體識別碼。entityIdNS
:您嘗試擷取的實體的名稱空間。 如果entityId
是 而非 XID,則必須提供此值。mergePolicyId
:實體的合併原則識別碼。 合併原則包含身分拼接和索引鍵/值XDM物件合併的相關資訊。 如果未提供此值,則會使用預設合併原則。
要求
以下請求會刪除指定的實體。
code language-shell |
---|
|
回應
成功的回應會傳回HTTP狀態202和空白的回應本文。
後續步驟
依照本指南,您已成功存取Real-Time Customer Profile資料欄位、設定檔和時間序列資料。 若要瞭解如何存取儲存在Experience Platform中的其他資料資源,請參閱資料存取總覽。
附錄 appendix
下節提供有關使用API存取Profile資料的補充資訊。
查詢參數 query-parameters
下列引數用於/access/entities
端點之GET要求的路徑。 它們用於識別您要存取的設定檔實體,並篩選回應中傳回的資料。 必要引數會加上標籤,其餘引數則為選用。
schema.name
schema.name=_xdm.context.profile
relatedSchema.name
schema.name
是_xdm.context.experienceevent
,此值 必須 為時間序列事件相關的設定檔實體指定結構描述。relatedSchema.name=_xdm.context.profile
entityId
entityIdNS
)。entityId=janedoe@example.com
entityIdNS
entityId
作為XID,此欄位 必須 指定身分名稱空間。entityIdNS=email
relatedEntityId
schema.name
是_xdm.context.experienceevent
,此值 必須 指定相關設定檔實體的識別碼。 此值遵循與entityId
相同的規則。relatedEntityId=69935279872410346619186588147492736556
relatedEntityIdNS
schema.name
是「_xdm.context.experienceevent」,此值必須為relatedEntityId
中指定的實體指定身分名稱空間。relatedEntityIdNS=CRMID
fields
fields=personalEmail,person.name,person.gender
mergePolicyId
mergePolicyId=5aa6885fcf70a301dabdfa4a
orderBy
(+/-)timestamp
,預設為+timestamp
。orderby=-timestamp
startTime
startTime=1539838505
endTime
endTime=1539838510
limit
limit=100
property
property=webPageDetails.isHomepage=true&property=localTime<="2020-07-20"