Základné operácie so segmentmi pomocou segmentačného API
Poznámka
Od 1. septembra 2023 sa aplikácie Dynamics 365 Marketing a Dynamics 365 Customer Insights budú predávať spoločne v rámci jednej skladovej jednotky produktu s názvom Dynamics 365 Customer Insights. Jednotlivé aplikácie sa premenujú na Dynamics 365 Customer Insights – Činnosti a Dynamics 365 Customer Insights – Údaje (v tomto poradí). Ďalšie informácie nájdete v časti Najčastejšie otázky týkajúce sa aplikácie Dynamics 365 Customer Insights
Okrem toho 1. septembra 2023 noví zákazníci využívajúci aplikáciu Dynamics 365 Marketing získajú iba funkcie marketingu v reálnom čase. Ďalšie informácie nájdete v časti Predvolená inštalácia marketingu v reálnom čase. Mnohé stránky s dokumentáciou v súčasnosti odkazujú na funkcie odchádzajúceho marketingu, ktoré nemusia byť dostupné alebo môžu v marketingu v reálnom čase fungovať inak. Obsah dokumentácie bude aktualizovaný v septembri a bude informovať o tom, či sa vzťahuje na marketing v reálnom čase alebo odchádzajúci marketing.
Dôležité
Tento článok sa týka iba outbound marketingu.
Segment trhu je kolekcia kontaktov, ktoré zacieľujete v marketingovej kampani. V niektorých prípadoch zacielite na všetky kontakty, ktoré máte, no vo väčšine prípadov si vyberiete, na koho chcete zacieliť, na základe demografických alebo firmografických údajov a iných úvah. Viac informácií: Práca so segmentmi.
Segmentation API umožňuje programovú interakciu so záznamami segmentov. Segmentation API využíva štandardné Microsoft Dataverse Web API na manipuláciu s entitami alebo správami. Ďalšie informácie: Použite Microsoft Dataverse Web API. Keď vytvoríte segment, vlastnosti segmentu sa uložia v entite msdyncrm_segment . Informácie o metadátach entity môžete prehliadať pomocou @odata.context
v odpovedi GET .
Poznámka
Pred vykonaním operácií by ste si mali nainštalovať Dynamics 365 Customer Insights - Journeys.
Táto téma ukazuje, ako vykonávať základné operácie na entite msdyncrm_segment . Ak chcete vytvoriť segment, zadajte nasledujúce povinné polia.
Display name | Názov schémy | Hodnota | Požaduje sa |
---|---|---|---|
Name | msdyncrm_segmentname | Názov segmentu. | Áno. |
Typ segmentu | msdyncrm_segmenttype | Typ segmentu. Existujú 3 typy segmentov: - Statické 192350001 - Dynamický 192350000 - Zmes 192350002 |
Áno. |
Dôvod stavu | kód stavu | Aktuálny stav segmentu. Nasledujú dostupné stavové kódy: - Návrh 192350000 - Naživo 192350001 - Zastavil 192350002 - Ideme naživo 192350006 - Zastavenie 192350007 |
Áno. |
Dotaz segmentu | msdyncrm_query | Dopyt v segmentačnom dotaze. | Áno (iba pre dynamické a zložené segmenty). |
Na otestovanie operácií môžete použiť nástroj Postman. Ďalšie informácie: Použite Postmana s webovým rozhraním API.
Operácie CRUD na statických segmentoch
Táto časť ukazuje, ako vykonávať základné operácie CRUD (vytvorenie, aktualizácia, načítanie a odstránenie) na statických segmentoch.
Vytvorte žiadosť
Táto požiadavka vytvorí nový statický segment s dvoma kontaktmi a statuscode
nastaveným na Draft
. Hlavička odpovede obsahuje adresu URL tohto novovytvoreného záznamu (inštancia entity), ktorá v zátvorkách obsahuje jedinečné ID (segmentID) pre tento záznam.
Dôležité
Musíte nahradiť OrgUrl
s https://<add your environment name, like 'myorg.crm'>.dynamics.com
. Názov prostredia môžete získať aj z Nastavenia ->Prispôsobenia ->Zdroje pre vývojárov.
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
"msdyncrm_segmentname": "StaticSegmentApi1",
"msdyncrm_segmenttype": 192350001,
"msdyncrm_segmentmemberids": "[\"crm1405f4ba-1ee9-e811-a99d-000d3a35f12f\",\"crm0604cdd1-1ee9-e811-a99d-000d3a35f12f\"]",
"statuscode": 192350000
}
Dôležité
Účelom predpony crm je jednoznačne uviesť typ identifikátora záznamu. Vyžaduje sa to, keď používate staršie riešenie segmentácie, ktoré štandardne používa iný typ identifikátora.
Žiadosť o aktualizáciu
So žiadosťou o aktualizáciu aktualizujete statuscode
statický segment na Going Live (192350006)
. Keď je požiadavka vykonaná, aktualizuje sa statuscode
na Live
.
PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
"statuscode": 192350006
}
Načítať žiadosť
S požiadavkou na obnovenie získate všetky statické segmenty, ktoré sú v stave Live
.
GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350001
Môžete tiež získať segmenty so špecifickými vlastnosťami.
GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$select=msdyncrm_segmentid,msdyncrm_segmentname,msdyncrm_segmentquery,msdyncrm_description
Odstrániť žiadosť
Požiadavkou na vymazanie vymažete vytvorený statický segment.
DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
Operácie CRUD na dynamických segmentoch
Táto časť ukazuje, ako vykonávať základné operácie CRUD (vytvorenie, aktualizácia, načítanie a odstránenie) na dynamických segmentoch. Dynamické segmenty sú založené na segmentovom dopyte (msdyncrm_segmentquery). Ďalšie informácie: Definícia dopytu segmentu.
Vytvorte žiadosť
Táto požiadavka vytvorí dynamický segment a nastaví statuscode
na Draft
.
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
"msdyncrm_segmentname": "Customers with name and email",
"msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
"msdyncrm_segmenttype": 192350000,
"statuscode": 192350000
}
Nasledujúca požiadavka vytvorí dynamický segment s podmieneným segmentovým dotazom na načítanie iba kontaktov, ktoré majú address1_city
pole nastavené na NewYork
alebo NewJersey
.
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
"msdyncrm_segmentname": "MySegment2",
"msdyncrm_segmentquery": "PROFILE(contact).FILTER((address1_city == 'NewYork' || address1_city == 'NewJersey'))",
"msdyncrm_segmenttype": 192350000,
"statuscode": 192350006
}
Nasledujúca požiadavka vytvorí nový dynamický segment a nastaví statuscode
na Going Live
.
POST api/data/v9.0/msdyncrm_segments
{
"msdyncrm_segmentname": "Customers with name and email",
"msdyncrm_segmenttype": 192350000,
"msdyncrm_segmentquery": "PROFILE(contact, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1) && ISNOTNULL(contact_1.fullname))",
"statuscode": 192350006
}
Žiadosť o aktualizáciu
Pomocou žiadosti o aktualizáciu aktualizujete stav dynamický segment na Going Live
.
PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
"statuscode": 192350006
}
Poznámka
Odporúča sa neposúvať segmenty priamo do stavu Live
.
Načítať žiadosť
Pomocou žiadosti o načítanie získate všetky dynamické segmenty, ktoré sú v stave Stop
.
GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002
Odstrániť žiadosť
So žiadosťou o odstránenie odstránite vytvorený dynamický segment.
DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
Operácie CRUD na zložených segmentoch
Táto časť ukazuje, ako vykonávať základné operácie CRUD (vytvorenie, aktualizácia, načítanie a odstránenie) na zložených segmentoch.
Vytvorte žiadosť
Táto požiadavka vytvorí zložený segment a nastaví statuscode
to Going Live
.
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_segments
{
"msdyncrm_segmentname": "my_compound_segment1",
"msdyncrm_segmenttype": 192350002,
"msdyncrm_query":"SEGMENT(segment1) UNION SEGMENT(segment2)",
"statuscode": 192350006
}
Žiadosť o aktualizáciu
Pomocou žiadosti o aktualizáciu aktualizujete stav zložený segment na Stopping
.
PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
"statuscode": 192350007
}
Poznámka
Odporúča sa neposúvať segmenty priamo do Stopped
stavu.
Načítať žiadosť
S požiadavkou na obnovenie získate všetky zložené segmenty, ktoré sú v stave Stop
.
GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002
Odstrániť žiadosť
So žiadosťou o odstránenie odstránite vytvorený zložený segment.
DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
Pridať/odstrániť kontakty do statických segmentov
Členov segmentu je možné pridať do statických segmentov kontaktov alebo z nich odstrániť. Kontakty môžete pridávať/odstraňovať buď zadaním definície dotazu, alebo zadaním konkrétnych ID kontaktov.
Niektoré z dôležitých aspektov, ktoré je potrebné zvážiť pri vykonávaní operácií pridania/odstránenia na členoch segmentu:
- Ako členov možno pridať/odobrať iba inštancie typu entity Kontakt .
- Ak poskytnuté ID kontaktu neexistujú, budú ignorované.
- Požiadavky na pridanie/odstránenie členov sa spracúvajú asynchrónne.
- Kontakty môžete pridávať/odstraňovať opakovaným vyvolaním koncového bodu, zvyčajne v dávkach vždy po 20 000 kontaktov.
Pridajte členov segmentu zadaním identifikátorov
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
"msdyncrm_segmentid": "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
"msdyncrm_operation": "addByIds",
"msdyncrm_memberids": "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]"
}
Odstráňte členov segmentu poskytnutím identifikátorov
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
"msdyncrm_segmentid": "59AC8BBF-57E7-E811-A9A9-000D3A35F403",
"msdyncrm_operation": "removeByIds",
"msdyncrm_memberids": "[\"B5672BDB-8899-43CB-9FA1-0AE4DC61DAD3\", \"694E1C8E-F704-4B23-9B07-E65DB1620E47\", \"A4A31E3D-DFCA-4765-8018-3BA7D5E376C7\"]"
}
Pridajte členov segmentu zadaním dotazu
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
"msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
"msdyncrm_operation": "addByQuery",
"msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}
Odstráňte členov segmentu zadaním dotazu
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
"msdyncrm_segmentid": "b5466fbb-2cef-e911-a81d-000d3a6d200c",
"msdyncrm_operation": "removeByQuery",
"msdyncrm_query": "PROFILE(account, account_1).FILTER(account_1.accountid == '1cc00a15-37ef-e911-a81d-000d3a6d200c').TRAVERSE(contact_account_parentcustomerid, contact_1).FILTER(ISNOTNULL(contact_1.emailaddress1))"
}
Získajte stav čakajúcich operácií
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
"msdyncrm_segmentid":"b5466fbb-2cef-e911-a81d-000d3a6d200c",
"msdyncrm_operation":"getState"
}
Získať členov segmentu (odporúčané)
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_FetchContactsByQuery
{
"Query":"(SEGMENT(SEGMENT_CRM_ID_e1fa7fdc5c78ea11a811000d3a8e8fcc)).ORDERBY(fullname ASC).SKIP(0).TAKE(15).SELECT(contactid)",
"FetchXml":"<fetch version=\"1.0\" output-format=\"xml-platform\" mapping=\"logical\" count=\"15\" page=\"1\" returntotalrecordcount=\"true\"><entity name=\"contact\"><attribute name=\"fullname\"/><attribute name=\"emailaddress1\"/><attribute name=\"company\"/><attribute name=\"parentcustomerid\"/><attribute name=\"contactid\"/><order attribute=\"fullname\" descending=\"false\"/></entity></fetch>","OwningBusinessUnit":"0b4b85cc-7f6c-ea11-a811-000d3a54d359",
"Scope":270100000,
"TimeZone":null
}
Dôležité
Vo vyššie uvedenom príklade nahraďte SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc názvom svojho segmentu na serveri, ako je to v poli msdyncrm_segmentqueryname vášho segmentu. Ak má váš segment id ce97cb9d-bd75-ea11-a811-000d3a8e8fcc
, táto hodnota bude SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc
.
Získať členov segmentu (zastarané)
GET {{OrgUrl}}/api/data/v9.0/contacts?fetchXml=fetch version="1.0" output-format="xml-platform" mapping="logical" returntotalrecordcount="true" page="1" count="5" no-lock="false">
<entity name="contact">
<attribute name="fullname"/>
<attribute name="contactid"/>
<order attribute="fullname" descending="false"/>
<link-entity name="msdyncrm_segment" from="msdyncrm_segmentid" to="msdyncrm_segmentmemberid" alias="bb">
<filter type="and">
<condition attribute="msdyncrm_segmentid" operator="eq" uitype="msdyncrm_segment" value="bfc9d5d6-d6aa-e911-a859-000d3a3159df"/>
</filter>
</link-entity>
</entity>
</fetch>
Overovanie segmentov
Pred vytvorením alebo úpravou segmentu môžete overiť novú definíciu pomocou vyhradeného koncového bodu overenia.
Koncový bod vždy vráti správu HTTP status OK a objekt s vlastnosťou ValidationResult
obsahujúcou pole chýb.
Ak existuje platná definícia, pole výsledkov bude prázdne. V opačnom prípade obsahuje záznamy o zistených problémoch. Definícia segmentu sa overí pri vytvorení záznamu a stavový kód sa nastaví na Prebieha naživo.
Overenie je zámerne preskočené, keď je segment vytvorený v stave Koncept . Zlyhanie overenia má tiež za následok HTTP 400 s chybovým hlásením v tele odpovede.
Overenie platnej definície segmentu
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
"msdyncrm_segmentname":"NewSegment",
"msdyncrm_segmentquery":"PROFILE(contact)",
"msdyncrm_segmenttype":192350000,
"statuscode":192350000
}
Odpoveď
{
…
"ValidationResult": "[]"
}
Overuje sa neplatná definícia segmentu
POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
"msdyncrm_segmentname":"NewSegment",
"msdyncrm_segmentquery":"PROFILE(UnknownEntity)",
"msdyncrm_segmenttype":192350000,
"statuscode":192350006
}
Odpoveď
{
…
"ValidationResult": "[{\"ErrorCode\":\"SegmentDciValidator_SegmentInvalid\",\"FieldName\":\"msdyncrm_query\"}]"
}