Osnovne operacije na segmentima pomoću API-ja za segmentiranje

Članak
09/13/2023

Napomena

1. rujna 2023. Dynamics 365 Marketing i Dynamics 365 Customer Insights prodavat će se zajedno kao jedan SKU proizvoda pod nazivom Dynamics 365 Customer Insights. Pojedinačne aplikacije preimenovat će se u Dynamics 365 Customer Insights – putovi i Dynamics 365 Customer Insights – podaci. Dodatne informacije potražite u Najčešćim pitanjima o sustavu Dynamics 365 Customer Insights

Nadalje, 1. runja 2023. novi klijenti s aplikacijom Dynamics 365 Marketing dobit će samo značajke marketinga u stvarnom vremenu. Dodatne informacije potražite u Zadana instalacija marketinga u stvarnom vremenu. Mnogo stranica dokumentacije trenutno upućuje na izlazne značajke koje možda nisu dostupne ili funkcioniraju drugačije u marketingu u stvarnom vremenu. Sadržaj dokumentacije ažurirat će se u rujnu kako bi se naznačilo odnosi li se na marketing u stvarnom vremenu ili na izlazni marketing.

Važno

Ovaj se članak odnosi samo na izlazni marketing.

Tržišni segment zbirka je kontakata koje ciljate u nekoj marketinškoj kampanji. U nekim ćete slučajevima ciljati sve kontakte koje imate, ali u većini slučajeva odabrat ćete koga želite ciljati na temelju demografskih ili firmografskih podataka i drugih razmatranja. Više informacija: Rad sa segmentima.

API segmentacije omogućuje programsku interakciju sa zapisima segmenata. API segmentacije koristi standardni Microsoft Dataverse web-API za rukovanje entitetima ili porukama. Dodatne informacije: Korištenje web-API-ja Microsoft Dataverse . Kada kreirate segment, svojstva segmenta pohranjuju se u msdyncrm_segment entitet. Informacije o metapodacima entiteta možete pregledavati pomoću @odata.context odgovora GET .

Napomena

Prije izvođenja operacija trebali biste instalirati Dynamics 365 Customer Insights - Putovanja.

Ova tema pokazuje kako obavljati osnovne operacije na msdyncrm_segment entitetu. Proslijedite sljedeća obavezna polja da biste kreirali segment.

Zaslonski naziv	Naziv sheme	Vrijednost	Obvezno
Ime/naziv	msdyncrm_segmentname	Naziv segmenta.	Da.
Vrsta segmenta	msdyncrm_segmenttype	Vrsta segmenta. Postoje 3 vrste segmenata: -Statički `192350001` -Dinamičan `192350000` -Spoj `192350002`	Da.
Razlog statusa	šifrastanja	Trenutno stanje segmenta. Slijede dostupni kodovi stanja: -Nacrt `192350000` -Živjeti `192350001` -Zaustavljen `192350002` - Going Live `192350006` -Plomba `192350007`	Da.
Upit segmenta	msdyncrm_query	Upit u upitu segmentiranja.	Da (samo za dinamičke i složene segmente).

Da biste testirali operacije, možete koristiti alat Poštar. Dodatne informacije: Koristite poštara s web-API-jem.

CRUD operacije na statičkim segmentima

Ovaj odjeljak pokazuje kako izvršiti osnovne CRUD (stvaranje, ažuriranje, dohvaćanje i brisanje) operacija na statičkim segmentima.

Stvori zahtjev

Ovaj zahtjev stvara novi statički segment s dva kontakta i statuscode postavljen je na Draft. Zaglavlje odgovora sadrži URL ovog novostvorenog zapisa (instance entiteta), koji u zagradi uključuje jedinstveni ID (IDPgmenata za ovaj zapis.

Važno

Morate zamijeniti OrgUrl https://<add your environment name, like 'myorg.crm'>.dynamics.com. Naziv okruženja možete dobiti i iz odjeljka Postavke-prilagodbe-resursi>> za razvojne inženjere.

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
}

Važno

Svrha crm prefiksa je nedvosmisleno naznačiti vrstu identifikatora zapisa. To je potrebno kada koristite naslijeđeno rješenje segmentiranja, koje po zadanom koristi drugu vrstu identifikatora.

Zahtjev za ažuriranjem

Pomoću zahtjeva za ažuriranjem ažurirate statuscode statički segment na Going Live (192350006). Kada se zahtjev izvrši, ažurira statuscode se na Live.

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

Dohvati zahtjev

Pomoću zahtjeva za dohvaćanje dohvaćate sve statičke segmente koji se nalaze u Live stanju.

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

Također možete dohvatiti segmente s određenim svojstvima.

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

Izbriši zahtjev

Pomoću zahtjeva za brisanje brišete stvorenu statički segment.

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

CRUD operacije na dinamičkim segmentima

Ovaj odjeljak prikazuje kako izvesti osnovne CRUD (stvaranje, ažuriranje, dohvaćanje i brisanje) operacija na dinamičkim segmentima. Dinamički segmenti temelje se na upitu segmenta (msdyncrm_segmentquery). Dodatne informacije: Definicija upita segmenta.

Stvori zahtjev

Ovaj zahtjev stvara dinamički segment i postavlja statuscode se 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
}

Sljedeći zahtjev stvara dinamički segment s upitom uvjetnog segmenta za dohvaćanje samo kontakata na koje je address1_city polje postavljeno NewYork na ili 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
}

Sljedeći zahtjev stvara novi dinamički segment i postavlja statuscode se 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
}

Zahtjev za ažuriranjem

Pomoću zahtjeva za ažuriranje ažurirate status dinamički segment na Going Live.

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

Napomena

Preporučuje se da se segmenti ne premještaju izravno u Live stanje.

Dohvati zahtjev

Pomoću zahtjeva za dohvaćanje dohvaćate sve dinamičke segmente koji se nalaze u Stop stanju.

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

Izbriši zahtjev

Pomoću zahtjeva za brisanje brišete dinamički segment koja je stvorena.

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

CRUD operacije na složenim segmentima

Ovaj odjeljak prikazuje kako izvršiti osnovne CRUD (stvaranje, ažuriranje, dohvaćanje i brisanje) operacija na složenim segmentima.

Stvori zahtjev

Ovaj zahtjev stvara složeni segment i postavlja statuscode se 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
}

Zahtjev za ažuriranjem

Pomoću zahtjeva za ažuriranjem ažurirate status složeni segment na Stopping.

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

Napomena

Preporučuje se da se segmenti ne premještaju izravno u Stopped stanje.

Dohvati zahtjev

Pomoću zahtjeva za dohvaćanje dohvaćate sve složene segmente koji se nalaze u Stop stanju.

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

Izbriši zahtjev

Pomoću zahtjeva za brisanje brišete složeni segment koja je stvorena.

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

Dodavanje/uklanjanje kontakata u statičke segmente

Članovi segmenta mogu se dodati u statičke segmente kontakata ili ukloniti iz njih. Kontakte možete dodavati/uklanjati pružanjem definicije upita ili pružanjem određenih ID-ova kontakata.

Neki od važnih aspekata koje je potrebno uzeti u obzir prilikom izvođenja operacija dodavanja/uklanjanja na članovima segmenata:

Samo instance vrste entiteta Kontakt mogu se dodati/ukloniti kao članovi.
Ako navedeni ID-ovi kontakata ne postoje, zanemaruju se.
Zahtjevi za dodavanje/uklanjanje članova obrađuju se asinkrono.
Kontakte možete dodavati/uklanjati pozivanjem krajnja točka više puta, obično u serijama do 20.000 kontakata svaki put.

Dodavanje članova segmenta pružanjem ID-ova

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

Uklanjanje članova segmenta unosom ID-ova

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

Dodavanje članova segmenta pružanjem upita

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

Uklanjanje članova segmenta pružanjem upita

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

Dohvaćanje statusa operacija na čekanju

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

Dohvati članove segmenta (preporuč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
}

Važno

Na gornjem primjeru zamijenite SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc nazivom segmenta u pozadinskom sustavu, kao što je to u msdyncrm_segmentqueryname polju vašeg segmenta. Ako vaš segment ima ID ce97cb9d-bd75-ea11-a811-000d3a8e8fcc, ta će vrijednost biti SEGMENT_CRM_ID_ce97cb9dbd75ea11a811000d3a8e8fcc.

Dohvati članove segmenta (zastarjelo)

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>

Provjera valjanosti segmenata

Prije stvaranja ili izmjene segmenta možete provjeriti novu definiciju pomoću namjenskog krajnja točka za provjeru valjanosti. Krajnja točka uvijek vraća HTTP status OK poruku i objekt sa svojstvom ValidationResult koje sadrži niz pogrešaka.

Ako postoji valjana definicija, polje rezultata prikazuje prazno. U suprotnom sadrži zapise za identificirane probleme. Definicija segmenta provjerava se na kreiranju zapisa i kodu stanja postavljenom na Going Live.

Provjera valjanosti namjerno se preskače prilikom stvaranja segmenta u stanju skice . Također nije uspjelo rezultate provjere valjanosti u HTTP 400 s porukom o pogrešci u tijelu odgovora.

Provjera valjane definicije segmenta

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

Odaziv

{
…
    "ValidationResult": "[]"
}

Provjera valjanosti definicije segmenta koja nije valjana

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

Odaziv

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

Dijeli putem

Osnovne operacije na segmentima pomoću API-ja za segmentiranje

CRUD operacije na statičkim segmentima

CRUD operacije na dinamičkim segmentima

CRUD operacije na složenim segmentima

Dodavanje/uklanjanje kontakata u statičke segmente

Provjera valjanosti segmenata

Dodatni resursi