Viðburðir og vefkrókar - Tilvísun

Yfirskjal: API_Reference.md Útfærslumappa: app/src/Task/ Kóðaeining: Cloud Event Message Events (Kóðaeining 65346)

Yfirlit

Cloud Events viðbótin veitir innfædd Business Central Ytri viðskiptaviðburðir sem gera ytri kerfum kleift að fá vefkrókstilkynningar þegar skilaboð í cloud events klárast eða mistakast. Þetta leyfir viðburðadrifnar hönnunarrnar þar sem ytri kerfi fá tilkynningar strax í stað þess að biðjast eftir stöðu.

Helstu eiginleikar:

Lágmarksupplýsingar í tilkynningum: Vefkrókar senda aðeins nauðsynlegar upplýsingar (MessageId, MessageType, Timestamp)
BC-samþætting: Notar staðlaðan Ytri viðskiptaviðburðaramma Business Central
Sjálfvirk endursendingarreyna: Innbyggð endurstillingarrök fyrir misheppnaðar vefkróksafhendinnar
Viðburðaáskriftir: Stilla áskriftir í gegnum Viðburðaáskriftarsíðu Business Central
Öruggt form: Ytri kerfi ná í öll svarsgögn í gegnum auðkennt API-kall eftir að þau fá tilkynningar

Uppbygging viðburðar

Ytri viðskiptaviðburðir

Ytri viðskiptaviðburðir Business Central gera ytri kerfum kleift að gerast áskrifendur að viðburðum og fá HTTP POST-tilkynningar þegar viðburðir eiga sér stað. Cloud Events viðbótin birtir tvo ytri viðskiptaviðburði:

CloudEventMessageCompleted: Er gefinn út þegar skilaboð eru afgreidd með velgengi
CloudEventMessageFailed: Er gefinn út þegar úrvinnsla skilaboða mistekst

Viðburðaflokkur

Allar Cloud Events vefkrókstilkynningar falla undir:

Heiti flokks: "Origo Cloud Event"
Viðburðaflokksviðbót: Kóðaeining 65300 Cloud Event Category

Þennan flokk má nota til að sía og skipuleggja viðburðaáskriftir í Business Central.

Form með lágmarksupplýsingum

Vefkrókstilkynningar senda viljandi lágmarksupplýsingar til að:

Auka öryggi: Svarsgögn geta innihaldið viðkvæmar viðskiptaupplýsingar
Draga úr bandaríkjum: Stórar svarsnargar myndu auka netgjaldsnotkun
Viðhalda sveigjanleika: Áskrifendur geta sótt nákvæmar upplýsingar þegar þeir eru tilbúnir
Styðja endursendingu: Minni nargar eru áreiðanlegri fyrir vefkrók endursendingarrök

Eftir að fá vefkrókstilkynningu kalla áskrifendur Cloud Event Data API með MessageId til að ná í öll svarsgögn.

Viðburður: CloudEventMessageCompleted

Tilgangur: Tilkynnir ytri kerfum þegar skilaboð í cloud events hafa lokið úrvinnslu með velgengi.

Viðburðarheiti: CloudEventMessageCompleted Birtiheiti viðburðar: Cloud Event Message Completed Viðburðaflokkur: Origo Cloud Event Gefinn út af: Kóðaeining 65313 Cloud Event Message Task

Þegar viðburðurinn er gefinn út

Viðburðurinn er gefinn út eftir að skilaboð í cloud events hafa verið afgreidd með velgengi:

Skilaboð eru lögð í biðröð í gegnum Queue API eða Task API
Úrvinnsla skilaboðanna hefst (í gegnum bakgrunnsverkefni eða samstillt)
Útfærslan keyrir viðskiptalegar aðgerðir með velgengi
Svarsgögn eru geymd í Cloud Event Message töflunni
Viðburðurinn er gefinn út með MessageId, MessageType og tímastimpli lokunar
Vefkrókstilkynning er send til allra áskrifenda
Áskrifendur fá tilkynningu og geta sótt svarsgögn

Umboð vefkróks

{
  "MessageId": "a8f5f167-8f2c-4a42-9b3e-5c6c7d8e9f0a",
  "MessageType": "Customer.CreditLimit.Get",
  "ResponseContentLink": "/api/origo/cloudEvent/v1.0/responses(a8f5f167-8f2c-4a42-9b3e-5c6c7d8e9f0a)/data",
  "Timestamp": "2026-03-08T14:30:22Z"
}

Reitir í umboðinu

Reitur	Tegund	Lýsing
`MessageId`	Guid	Einkvæmt auðkenni skilaboðanna. Notaðu þetta til að kalla GET /cloudEventData(MessageId) til að ná í öll svarsgögn.
`MessageType`	Text[250]	Tegund skilaboðanna sem klárast (t.d. "Customer.CreditLimit.Get", "Data.Records.Get"). Hægt að nota til leiðarins eða síunar.
`ResponseContentLink`	Text[250]	Bein API-tengill til að sækja svarsgögn. Notaðu þessa slóð til að ná í öll svar án þess að smíða API-slóðina handvirkt.
`Timestamp`	DateTime	Þegar skilaboðin klárðust (ISO 8601 snið).

Að ná í öll svarsgögn

Eftir að fá vefkrókstilkynningu, kalaðu Cloud Event Data API til að ná í öll svarsgögn:

Beiðni:

GET /api/origo/cloudEvent/v1.0/responses('{message-id}')
Authorization: Bearer {token}

Svar:

{
  "id": "a8f5f167-8f2c-4a42-9b3e-5c6c7d8e9f0a",
  "data": "... öll svarsgögn sem base64 eða JSON ..."
}

Dæmi um samþættingarflæði

sequenceDiagram
    participant External as Ytri kerfi
    participant BCQueue as BC Queue API
    participant BCTask as BC Task afgreiðsluþjónn
    participant Webhook as Vefkróksendapunktur
    participant BCData as BC Data API

    External->>BCQueue: POST /cloudEventQueue (skilaboð)
    BCQueue-->>External: 202 Accepted (MessageId)
    
    BCTask->>BCTask: Afgreiðir skilaboð
    BCTask->>BCTask: Geymir svarsgögn
    BCTask->>Webhook: POST vefkrókur (MessageId, tegund, tími)
    
    Webhook->>BCData: GET /cloudEventData(MessageId)
    BCData-->>Webhook: Svarsgögn
    Webhook->>Webhook: Vinnur úr svari

Notkunartilvik

Ósamstillt úrvinnsla: Ytri kerfi fær tafarlausar tilkynningar þegar langvarandi aðgerðir klárast
Viðburðadrifin hönnun: Sett af stað verkflæði í ytri kerfum byggt á lokun BC skilaboða
Rauntímasamþætting: Lágmarka tafir milli BC-úrvinnslu og viðbragðs ytri kerfis
Ótengd kerfi: Ytri kerfi þurfa ekki að biðjast eftir stöðu frá BC

Viðburður: CloudEventMessageFailed

Tilgangur: Tilkynnir ytri kerfum þegar úrvinnsla skilaboða í cloud events hefur mistekist.

Viðburðarheiti: CloudEventMessageFailed Birtiheiti viðburðar: Cloud Event Message Failed Viðburðaflokkur: Origo Cloud Event Gefinn út af: Kóðaeining 65312 Cloud Event Message Error

Þegar viðburðurinn er gefinn út

Viðburðurinn er gefinn út eftir að úrvinnsla skilaboða í cloud events hefur mistekist:

Skilaboð eru lögð í biðröð í gegnum Queue API eða Task API
Úrvinnsla skilaboðanna hefst (í gegnum bakgrunnsverkefni eða samstillt)
Útfærslan lendir í villu eða sannvottun mistekst
Villuupplýsingar eru fangaðar og geymdar í Cloud Event Message töflunni
Viðburðurinn er gefinn út með MessageId, MessageType og tímastimpli mistaks
Vefkrókstilkynning er send til allra áskrifenda
Áskrifendur fá tilkynningu og geta sótt villuupplýsingar

Umboð vefkróks

{
  "MessageId": "b9f6f267-9f3d-5b52-0c4f-6d7d8e9f1b1b",
  "MessageType": "Data.Records.Set",
  "ResponseContentLink": "/api/origo/cloudEvent/v1.0/responses(b9f6f267-9f3d-5b52-0c4f-6d7d8e9f1b1b)/data",
  "Timestamp": "2026-03-08T14:35:18Z"
}

Reitir í umboðinu

Reitur	Tegund	Lýsing
`MessageId`	Guid	Einkvæmt auðkenni skilaboðanna. Notaðu þetta til að kalla GET /cloudEventQueue(MessageId) til að ná í villuupplýsingar.
`MessageType`	Text[250]	Tegund skilaboðanna sem mistókst (t.d. "Data.Records.Set", "Sales.Document.Release").
`ResponseContentLink`	Text[250]	Bein API-tengill til að sækja villuupplýsingar. Notaðu þessa slóð til að ná í villusvari án þess að smíða API-slóðina handvirkt.
`Timestamp`	DateTime	Þegar úrvinnsla skilaboðanna mistókst (ISO 8601 snið).

Að ná í villuupplýsingar

Eftir að fá vefkrókstilkynningu, kalaðu Cloud Event Queue API til að ná í villuupplýsingar:

Beiðni:

GET /api/origo/cloudEvent/v1.0/queues('{message-id}')
Authorization: Bearer {token}

Svar:

{
  "id": "b9f6f267-9f3d-5b52-0c4f-6d7d8e9f1b1b",
  "type": "Data.Records.Set",
  "specversion": "1.0",
  "source": "MyIntegrationApp v1.0",
  "time": "2026-03-08T14:35:15Z",
  "datacontenttype": "text/json",
  "data": "{
    \"error\": \"Record not found\",
    \"detailedMessage\": \"Table: Customer, SystemId: {guid}\",
    \"stackTrace\": \"...\",
    \"callStack\": \"...\"
  }"
}

Snið villusvars

Villusvar er geymt á JSON-sniði með eftirfarandi reitum:

error: Stutt villutilkynning
detailedMessage: Nákvæm villuframsetning
stackTrace: Öll stafla (ef til staðar)
callStack: Kallstafla á villutíma (ef til staðar)

Notkunartilvik

Villufylgjast með: Ytri kerfi geta skráð og sent viðvörun um bilanir strax
Sjálfvirk endursendingarreyna: Ytri kerfi geta útfært endurhleðslu-rök með veldisreiknum bið
Villugreining: Ná í nákvæmar villuupplýsingar til úrræðaleitunar
SLA-eftirlit: Fylgjast með úrvinnslubilonum og svartíma

Samþættingarviðburðir

Auk Ytri viðskiptaviðburða fyrir vefkróka veitir Cloud Events viðbótin Samþættingarviðburði sem leyfa öðrum Business Central viðbótum að bregðast við skilaboðalíftímaviðburðum.

OnBeforeCloudEventMessageProcessing

Tilgangur: Gefinn út áður en úrvinnsla skilaboða í cloud events hefst.

Viðburðartegund: IntegrationEvent Aðgengi: Internal Gefinn út af: Kóðaeining 65313 Cloud Event Message Task

Undirskrift:

[IntegrationEvent(false, false)]
internal procedure OnBeforeCloudEventMessageProcessing(var CloudEventMessage: Record "Cloud Event Message")

Færibreytur:

CloudEventMessage: Skilaboðafærslan sem er að fara í vinnslu (sent með tilvísun, hægt að breyta)

Notkunartilvik:

Sannprófun fyrir úrvinnslu: Sannreyna gögn skilaboða áður en úrvinnsla hefst
Gagnabæting: Bæta við viðbótarsamhengi eða lýsigögnum við skilaboðin
Telemetría: Skrá upphaf úrvinnslu skilaboða
Sérsniðin leiðsögn: Breyta tegund eða gögnum skilaboða byggt á sérsniðnum rökum

OnAfterCloudEventMessageCompleted

Tilgangur: Gefinn út eftir að skilaboð í cloud events hefur lokið með velgengi.

Viðburðartegund: IntegrationEvent Aðgengi: Internal Gefinn út af: Kóðaeining 65313 Cloud Event Message Task

Undirskrift:

[IntegrationEvent(false, false)]
internal procedure OnAfterCloudEventMessageCompleted(var CloudEventMessage: Record "Cloud Event Message")

Færibreytur:

CloudEventMessage: Skráin fyrir klárað skilaboðið (sent með tilvísun)

Notkunartilvik:

Vinnsla eftirá: Framkvæma viðbótaraðgerðir eftir velgengna úrvinnslu
Gagnassamstilling: Samstilla gögn skilaboða við aðrar töflur eða kerfi
Telemetría: Skrá lokunarmælingar (tímalengd, stærð o.s.frv.)
Verkflæðishlekkjun: Hefja háð verkflæði eða ferla

OnAfterCloudEventMessageFailed

Tilgangur: Gefinn út eftir að úrvinnsla skilaboða í cloud events hefur mistekist.

Viðburðartegund: IntegrationEvent Aðgengi: Internal Gefinn út af: Kóðaeining 65312 Cloud Event Message Error

Undirskrift:

[IntegrationEvent(false, false)]
internal procedure OnAfterCloudEventMessageFailed(var CloudEventMessage: Record "Cloud Event Message"; ErrorText: Text)

Færibreytur:

CloudEventMessage: Skráin fyrir misheppnaðan skilaboðið (sent með tilvísun)
ErrorText: Texti villuskilaboðanna

Notkunartilvik:

Villuskráning: Skrá villur í sérsniðnar skráningartöflur
Viðvörunargerð: Senda viðvaranir í gegnum tölvupóst eða aðrar leiðir
Sjálfvirk bata: Reyna sjálfvirka endurheimtu eða lagfæringu gagna
Greiningar: Fylgjast með villumynstrum og bilunartíðni

Uppsetning vefkróksáskrifta

Forskilyrði

Ytri vefkróksendapunktur: Þú þarft HTTPS-endapunkt sem getur tekið við POST-beiðnum
Kröfur til endapunkts:

Verður að styðja HTTPS (ekki HTTP)
Verður að svara með 2xx stöðukóða innan tímamarka (sjálfgefið 30 sekúndur)
Ætti að meðhöndla tvíteknar tilkynningar (einkvæmni)
Ætti að útfæra veldisvísisvöxt bið fyrir endursendingar

Stillingarskref

Skref 1: Farðu á Viðburðaáskriftir

Opnaðu BC vafraviðmót
Leitaðu að "Event Subscriptions"
Opnaðu Viðburðaáskriftarsíðuna

Skref 2: Búðu til nýja áskrift

Smelltu á Nýtt
Fylltu inn eftirfarandi reiti:

Reitur	Gildi	Lýsing
Subscriber ID	(Sjálfkrafa)	Einkvæmt auðkenni áskriftarinnar
Event Name	`CloudEventMessageCompleted` eða `CloudEventMessageFailed`	Veldu hvaða viðburð á að gerast áskrifandi að
Company Name	Heiti fyrirtækisins þíns	Fyrirtækjasamhengi viðburðarins
Event Category	`Origo Cloud Event`	Sía í Cloud Events flokk
Endpoint URL	`https://your-domain.com/webhook/bc-cloud-events`	Slóð vefkróksendapunktsins þíns
Authentication	(Veldu aðferð)	Hvernig á að auðkenna við endapunktinn þinn

Skref 3: Stilla auðkenningu

Veldu auðkenningaraðferð:

Valkostur 1: OAuth 2.0 (Mælt með)

Grant Type: Client Credentials
Authorization URL: OAuth-veituslóð þín
Client ID: OAuth-biðlaraauðkenni þitt
Client Secret: OAuth-biðlaraleynd þín
Token URL: OAuth-táknaendapunktur þinn

Valkostur 2: Grunnauðkenning

Username: Grunnauðkenningarnotendanafn þitt
Password: Grunnauðkenningarlykillinn þinn

Valkostur 3: API-lykill

API Key Name: Hausnafn (t.d. "X-API-Key")
API Key Value: API-lykillinn þinn

Valkostur 4: Ekkert

Engin auðkenning (ekki mælt með í framleiðslu)

Skref 4: Prófaðu áskriften

Notaðu "Test Subscription" aðgerðina til að senda prófunarviðburð
Staðfestu að endapunkturinn þinn fær prófunarumboðið
Athugaðu "Last Delivery Status" reitinn fyrir velgengi/bilun

Skref 5: Virkjaðu áskriften

Stilltu "Enabled" reitinn á Já
Áskriftin er nú virk og mun fá viðburði

Bestu venjur vefkróksendapunkts

1. Einkvæmni

Endapunkturinn þinn ætti að meðhöndla tvíteknar tilkynningar af þolinmæði:

// Dæmi: Node.js Express endapunktur
app.post('/webhook/bc-cloud-events', async (req, res) => {
  const { MessageId, MessageType, ResponseContentLink, Timestamp } = req.body;
  
  // Athugaðu hvort við höfum þegar meðhöndlað þessi skilaboð
  const exists = await db.checkMessageProcessed(MessageId);
  if (exists) {
    console.log(`Tvítekin tilkynning fyrir ${MessageId}, hunsa`);
    return res.status(200).send('OK'); // Skiltu samt 200 til að koma í veg fyrir endursendingu
  }
  
  // Merktu sem í vinnslu áður en gögnum er sótt
  await db.markMessageProcessing(MessageId);
  
  // Sæktu öll svarsgögn frá BC með gefnum tengli
  const response = await fetchCloudEventData(ResponseContentLink);
  
  // Vinndu úr svarinu
  await processResponse(response, MessageType);
  
  // Merktu sem kláraðan
  await db.markMessageCompleted(MessageId);
  
  res.status(200).send('OK');
});

2. Ósamstillt úrvinnsla

Svaraðu vefkróknum fljótt og vinndu gögn ósamstillt:

app.post('/webhook/bc-cloud-events', async (req, res) => {
  const { MessageId, MessageType, ResponseContentLink, Timestamp } = req.body;
  
  // Settu strax í biðröð fyrir bakgrunnsvinnslu
  await queue.enqueue({
    messageId: MessageId,
    messageType: MessageType,
    responseContentLink: ResponseContentLink,
    timestamp: Timestamp
  });
  
  // Svaraðu strax
  res.status(200).send('OK');
});

// Bakgrunnsverkmaður vinnur biðröðina
backgroundWorker.on('job', async (job) => {
  const response = await fetchCloudEventData(job.responseContentLink);
  await processResponse(response, job.messageType);
});

3. Villumeðhöndlun

Útfærðu viðeigandi villumeðhöndlun og skráningu:

app.post('/webhook/bc-cloud-events', async (req, res) => {
  try {
    const { MessageId, MessageType, ResponseContentLink, Timestamp } = req.body;
    
    // Staðfesttu umboð
    if (!MessageId || !MessageType || !ResponseContentLink || !Timestamp) {
      console.error('Ógilt umboð móttekið', req.body);
      return res.status(400).send('Invalid payload');
    }
    
    // Settu í biðröð fyrir vinnslu
    await queue.enqueue({
      messageId: MessageId,
      messageType: MessageType,
      responseContentLink: ResponseContentLink,
      timestamp: Timestamp
    });
    
    res.status(200).send('OK');
  } catch (error) {
    console.error('Villa við vefkróksvinnuslu:', error);
    // Skilaðu 4xx fyrir biðlaravillur (ekki endurreyna)
    // Skilaðu 5xx fyrir þjónaravillur (BC mun endurreyna)
    res.status(500).send('Internal Server Error');
  }
});

4. Meðhöndlun endursendinga

Meðhöndlaðu endursendingar með veldisreiknum bið þegar gögn eru sótt frá BC:

async function fetchCloudEventData(messageId, maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      const response = await bcApi.get(`/cloudEventData(${messageId})`);
      return response.data;
    } catch (error) {
      if (attempt === maxRetries) throw error;
      
      // Veldisreikinn bið: 1s, 2s, 4s
      const delay = Math.pow(2, attempt - 1) * 1000;
      await sleep(delay);
    }
  }
}

5. Eftirlit og viðvaranir

Útfærðu eftirlit fyrir bilanir í afhendingu vefkróka:

app.post('/webhook/bc-cloud-events', async (req, res) => {
  const startTime = Date.now();
  
  try {
    const { MessageId, MessageType, Timestamp } = req.body;
    
    await queue.enqueue({
      messageId: MessageId,
      messageType: MessageType,
      timestamp: Timestamp
    });
    
    // Fylgstu með velgengismælingar
    metrics.webhookReceived(MessageType);
    metrics.webhookLatency(Date.now() - startTime);
    
    res.status(200).send('OK');
  } catch (error) {
    // Fylgstu með bilanarmælingar
    metrics.webhookFailed(error);
    
    // Sendu viðvörun um alvarleg mistök
    if (shouldAlert(error)) {
      alerting.sendAlert('Villa við vinnuslu vefkróks', error);
    }
    
    res.status(500).send('Internal Server Error');
  }
});

Prófun vefkróka

Prófunarskil á skilaboðum

Leggðu fram prófunarskilaboð til að kveikja á vefkrókstilkynningum:

# Leggðu fram prófunarskilaboð í Queue API
curl -X POST "https://your-bc-instance/api/origo/cloudEvent/v1.0/queues" \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "specversion": "1.0",
    "type": "Help.Tables.Get",
    "source": "Webhook Test v1.0"
  }'

Fylgjast með afhendingu viðburðar

Opnaðu Viðburðaáskriftir síðuna í Business Central
Finndu áskriftina þína
Athugaðu eftirfarandi reiti:

Last Delivery Status: Velgengni/Mistök
Last Delivery Attempt: Tímastimpill síðustu afhendingartilraunar
Last Delivery Error: Villuskilaboð ef afhending mistókst

Úrræðaleit

Vefkrókur tekur ekki við viðburðum

Athugaðu stöðu áskriftar: Gakktu úr skugga um að áskriftin sé Virkjuð
Staðfestu heiti viðburðar: Gakktu úr skugga um að þú sért áskrifandi að réttu viðburðinum (CloudEventMessageCompleted eða CloudEventMessageFailed)
Athugaðu endapunktsslóð: Staðfestu að slóðin sé rétt og aðgengileg
Prófaðu tengingu: Notaðu "Test Subscription" aðgerðina í Viðburðaáskriftum
Farðu yfir eldveggslegar reglur: Gakktu úr skugga um að BC geti náð endapunktinum þínum
Athugaðu auðkenningu: Staðfestu að skilríki séu rétt

Afhendingarbilanir

Athugaðu svartíma endapunkts: Verður að svara innan tímamarka (sjálfgefið 30s)
Staðfestu HTTPS: Endapunktur verður að nota HTTPS, ekki HTTP
Athugaðu stöðukóða: Endapunktur verður að skila 2xx stöðukóða
Farðu yfir villukladda: Athugaðu "Last Delivery Error" reitinn í Viðburðaáskriftum
Prófaðu handvirkt: Kalaðu endapunktinn þinn beint með dæmilegum umboðum

Tvíteknar tilkynningar

Business Central gæti sent tvíteknar tilkynningar í tilteknum aðstæðum:

Nettímamörk (BC fékk ekki svar í tæka tíð)
Endursendingarbilanir (endapunktur skilaði 5xx villu)
Kerfisendurræsing við afhendingu

Lausn: Útfærðu einkvæmni í vefkróksendapunktinum þínum (sjá Bestu venjur hér að ofan)