Deli z drugimi prek

Osnovne operacije na segmentih z uporabo segmentacijskega API-ja

  • Članek

opomba,

1. septembra 2023 bosta Dynamics 365 Marketing in Dynamics 365 Customer Insights na prodaj skupaj v okviru ene inventarne enote izdelka, imenovane Dynamics 365 Customer Insights. Posamezni aplikaciji bosta preimenovani v Dynamics 365 Customer Insights – Dejavnosti oziroma Dynamics 365 Customer Insights – Podatki. Več informacij je v pogostih vprašanjih za Dynamics 365 Customer Insights

Poleg tega bodo 1. septembra 2023 novi uporabniki storitve Dynamics 365 Marketing prejeli samo funkcije sprotnega trženja. Več informacij je v razdelku Privzeta namestitev sprotnega trženja. Številne strani z dokumentacijo se trenutno nanašajo na odhodne funkcije, ki v sprotnem trženju morda niso na voljo ali delujejo drugače. Vsebina dokumentacije bo posodobljena septembra, da bo razvidno, ali se nanaša na sprotno ali odhodno trženje.

Pomembno

Ta članek se nanaša samo na izhodno trženje.

Tržni segment je zbirka stikov, ki jih ciljate v trženjski akciji. V nekaterih primerih boste ciljali na vse stike, ki jih imate, vendar boste v večini primerov izbrali, na koga želite ciljati, na podlagi demografskih ali firmografskih podatkov in drugih premislekov. Več informacij: Delo s segmenti.

API za segmentacijo omogoča programsko interakcijo z zapisi segmentov. API za segmentacijo izkorišča standardni Microsoft Dataverse spletni API za manipuliranje z entitetami ali sporočili. Več informacij: Uporabite Microsoft Dataverse spletni API. Ko ustvarite segment, so lastnosti segmenta shranjene v entiteti msdyncrm_segment . Po informacijah o metapodatkih entitete lahko brskate z uporabo @odata.context v GET odgovoru.

opomba,

Preden izvedete operacije, morate namestiti Dynamics 365 Customer Insights - Journeys.

Ta tema prikazuje, kako izvajati osnovne operacije na entiteti msdyncrm_segment . Če želite ustvariti segment, izpolnite naslednja obvezna polja.

Prikazno ime Ime sheme Vrednost Zahtevano
Imenu ime_segmenta msdyncrm Ime segmenta. Da.
Vrsta segmenta msdyncrm_segmenttype Vrsta segmenta. Obstajajo 3 vrste segmentov:
- Statično 192350001
- Dinamično 192350000
- Spojina 192350002		 Da.
Razlog stanj koda stanja Trenutno stanje segmenta. Na voljo so naslednje statusne kode:
- Osnutek 192350000
- V živo 192350001
- Ustavljeno 192350002
- GoingLive 192350006
- Ustavljanje 192350007		 Da.
Poizvedba segmenta msdyncrm_query Poizvedba v poizvedbi za segmentacijo. Da (samo za dinamične in sestavljene segmente).

Za preizkus operacij lahko uporabite orodje Postman. Več informacij: Uporabite Poštar s spletnim API-jem.

CRUD operacije na statičnih segmentih

Ta razdelek prikazuje, kako izvajati osnovne operacije CRUD (ustvarjanje, posodabljanje, pridobivanje in brisanje) na statičnih segmentih.

Ustvari zahtevo

Ta zahteva ustvari nov statični segment z dvema stikoma in statuscode nastavljenim na Draft. Glava odgovora vsebuje URL do tega na novo ustvarjenega zapisa (primerka entitete), ki v oklepaju vključuje enolični ID (segmentID) za ta zapis.

Pomembno

Morate zamenjati OrgUrl z https://<add your environment name, like 'myorg.crm'>.dynamics.com. Ime okolja lahko dobite tudi v Nastavitve ->Prilagajanja ->Viri za razvijalce.

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
}

Pomembno

Namen predpone crm je nedvoumno navesti vrsto identifikatorja zapisa. To je potrebno, če uporabljate podedovano rešitev za segmentacijo, ki privzeto uporablja drugo vrsto identifikatorja.

Zahteva za posodobitev

Z zahtevo za posodobitev posodobite statuscode statični segment na Going Live (192350006). Ko je zahteva izvedena, se posodobi statuscode na Live.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
  "statuscode": 192350006
}

Pridobi zahtevo

Z zahtevo za pridobitev pridobite vse statične segmente, ki so v stanju Live .

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350001

Pridobite lahko tudi segmente z določenimi lastnostmi.

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$select=msdyncrm_segmentid,msdyncrm_segmentname,msdyncrm_segmentquery,msdyncrm_description

Izbriši zahtevo

Z zahtevo za brisanje izbrišete ustvarjeno statični segment.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

CRUD operacije na dinamičnih segmentih

Ta razdelek prikazuje, kako izvajati osnovne operacije CRUD (ustvarjanje, posodabljanje, pridobivanje in brisanje) na dinamičnih segmentih. Dinamični segmenti temeljijo na segmentni poizvedbi (msdyncrm_segmentquery). Več informacij: Definicija poizvedbe segmenta.

Ustvari zahtevo

Ta zahteva ustvari dinamični segment in nastavi 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
}

Naslednja zahteva ustvari dinamični segment s poizvedbo pogojnega segmenta za pridobitev samo stikov, ki imajo polje address1_city nastavljeno na NewYork ali 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
}

Naslednja zahteva ustvari nov dinamični segment in nastavi 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
}

Zahteva za posodobitev

Z zahtevo za posodobitev posodobite status dinamični segment na Going Live.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350006
}

opomba,

Priporočljivo je, da segmentov ne premikate neposredno v Live stanje.

Pridobi zahtevo

Z zahtevo za pridobitev pridobite vse dinamične segmente, ki so v stanju Stop .

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Izbriši zahtevo

Z zahtevo za brisanje izbrišete dinamični segment, ki je ustvarjen.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

Operacije CRUD na sestavljenih segmentih

Ta razdelek prikazuje, kako izvajati osnovne operacije CRUD (ustvarjanje, posodabljanje, pridobivanje in brisanje) na sestavljenih segmentih.

Ustvari zahtevo

Ta zahteva ustvari sestavljeni segment in nastavi statuscode na 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
}

Zahteva za posodobitev

Z zahtevo za posodobitev posodobite status sestavljeni segment na Stopping.

PATCH {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})
{
    "statuscode": 192350007
}

opomba,

Priporočljivo je, da segmentov ne premikate neposredno v Stopped stanje.

Pridobi zahtevo

Z zahtevo za pridobitev pridobite vse sestavljene segmente, ki so v stanju Stop .

GET {{OrgUrl}}/api/data/v9.0/msdyncrm_segments?$filter=statuscode eq 192350002

Izbriši zahtevo

Z zahtevo za brisanje izbrišete sestavljeni segment, ki je ustvarjen.

DELETE {{OrgUrl}}/api/data/v9.0/msdyncrm_segments({{SegmentId}})

Dodajanje/odstrani stike v statične segmente

Člane segmenta lahko dodate ali odstranite iz statičnih segmentov stikov. Stike lahko dodajate/odstranjujete tako, da navedete definicijo poizvedbe ali navedete posebne ID-je stikov.

Nekateri pomembni vidiki, ki jih je treba upoštevati pri izvajanju operacij dodajanja/odstranjevanja članov segmenta:

  • Kot člane je mogoče dodati/odstraniti samo primerke tipa entitete Stik .
  • Če posredovani ID-ji stikov ne obstajajo, so prezrti.
  • Zahteve za dodajanje/odstranjevanje članov se obdelujejo asinhrono.
  • Stike lahko dodajate/odstranjujete tako, da večkrat pokličete končna točka, običajno v serijah do 20.000 stikov vsakič.

Dodajte člane segmenta z vnosom ID-jev

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

Odstranite člane segmenta z vnosom ID-jev

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

Dodajte člane segmenta z vnosom poizvedbe

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))"
}

Odstranite člane segmenta z vnosom poizvedbe

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))"
}

Pridobite status čakajočih operacij

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_SegmentMembersUpdate
{
    "msdyncrm_segmentid":"b5466fbb-2cef-e911-a81d-000d3a6d200c",
    "msdyncrm_operation":"getState"
}

Pridobi člane segmenta (priporočeno)

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
}

Pomembno

V zgornjem primeru zamenjajte SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc z imenom svojega segmenta v ozadju, kot je v polju msdyncrm_segmentqueryname vašega segmenta. Če ima vaš segment ID ce97cb9d-bd75-ea11-a811-000d3a8e8fcc, bo ta vrednost SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc.

Pridobi člane segmenta (zastarelo)

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>

Preverjanje segmentov

Preden ustvarite ali spremenite segment, lahko preverite novo definicijo z namenskim preverjanjem končna točka. Končna točka vedno vrne sporočilo o statusu HTTP OK in objekt z lastnostjo ValidationResult , ki vsebuje niz napak.

Če obstaja veljavna definicija, je matrika rezultatov prazna. V nasprotnem primeru vsebuje zapise za ugotovljene težave. Definicija segmenta je potrjena ob ustvarjanju zapisa, statusna koda pa je nastavljena na V živo.

Preverjanje veljavnosti je namerno preskočeno, ko je segment ustvarjen v stanju Osnutek . Prav tako neuspešno preverjanje povzroči HTTP 400 s sporočilom o napaki v telesu odgovora.

Preverjanje veljavne definicije segmenta

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(contact)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350000
}

Odziv

{
…
    "ValidationResult": "[]"
}

Preverjanje neveljavne definicije segmenta

POST {{OrgUrl}}/api/data/v9.0/msdyncrm_ValidateSegment
{
       "msdyncrm_segmentname":"NewSegment",
       "msdyncrm_segmentquery":"PROFILE(UnknownEntity)",
       "msdyncrm_segmenttype":192350000,
       "statuscode":192350006
}

Odziv

{
…
    "ValidationResult": "[{\"ErrorCode\":\"SegmentDciValidator_SegmentInvalid\",\"FieldName\":\"msdyncrm_query\"}]"
}