Zdieľať cez


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\"}]"
}