Cloud Events API — Tilvísun

Yfirlit

Origo Cloud Events-endingurinn veitir API-endapunkta til að stjórna og vinna með skilaboð í samræmi við CloudEvents-staðalinn. Þetta skjal lýsir öllum tiltækum API-endapunktum og studdum skilaboðategundum.

Nafnrými: Origo.PTE.CloudEvents API-útgefandi: origo API-hópur: cloudEvent API-útgáfa: v1.0

API-endapunktar

1. Cloud Event Data API — Svarsgögn

Tilgangur: Skilar svarsgagnasniðið fyrir tiltekin skilaboð.

Endapunktsupplýsingar:

• Einingaheiti: response
• Einingasettaheiti: responses
• Grunnslóð: /api/origo/cloudEvent/v1.0/responses
• Aðgangur: Eingöngu lestur (engar setja-inn eða breyta-aðgerðir)

Reitir:

Studdar aðgerðir:

• GET (ein): Sækir svarsgögn fyrir tiltekin skilaboð eftir auðkenni
• GET (safn): Sækir öll svarsgagnagildi

Dæmi um beiðni:

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

1b. Cloud Event Request Data API — Upprunalegar beiðnigögn

Tilgangur: Skilar upprunalegar beiðnigögn fyrir tiltekin skilaboð. Gagnlegt til að skoða eða endursenda beiðni.

Endapunktsupplýsingar:

• Einingaheiti: request
• Einingasettaheiti: requests
• Grunnslóð: /api/origo/cloudEvent/v1.0/requests
• Aðgangur: Eingöngu lestur

Reitir:

Sækja gögn beint (ráðlæg leið):

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

Öryggi: Niðurstöður eru sjálfkrafa síaðar að færslum sem voru stofnaðar af kallandi forrita (SystemCreatedBy = UserSecurityId()).

2. Cloud Event Queue API

Tilgangur: Stofna skilaboðabeiðnir og fá stöður fyrir í biðröð (ósamstillt) skilaboð.

Endapunktsupplýsingar:

• Einingaheiti: queue
• Einingasettaheiti: queues
• Grunnslóð: /api/origo/cloudEvent/v1.0/queues
• Vinnsluháttur: Ósamstilltur (skilaboð eru tímasett fyrir bakgrunnsvinnslu)

Reitir:

Studdar aðgerðir:

POST — Stofna biðraðarskilaboð

Stofnar nýja skilaboðabeiðni sem verður unnin ósamstillt.

Dæmi um beiðnisniðmát:

{
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "lcid": 1033
}

Svar: Skilar stofnuðum skilaboðum með úthlutaðri auðkenni og tímastimpli. Þegar vinnsla er lokið mun data reiturinn innihalda niðurhalsslóð til að sækja svarsgögnin.

GET — Sækja biðraðarskilaboð

GET /api/origo/cloudEvent/v1.0/queues

Queue API-aðgerðir

RetryTask

Reynir aftur vinnslu skilaboða í Cloud Event.

Endapunktur:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.RetryTask

HTTP-stöðugildi:

CancelTask

Hættir við tímasett verk fyrir skilaboð í Cloud Event.

Endapunktur:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.CancelTask

HTTP-stöðugildi:

GetStatus

Sækir stöðu skilaboða í Cloud Event.

Endapunktur:

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.GetStatus

Stöðugildi:

• Created: Skilaboðin eru enn í vinnslu
• Deleted: Ekki er tímasett verk
• Updated: Vinnslu er lokið og niðurstöður eru tiltækar
• None: Staða skilaboðanna er óþekkt

3. Cloud Event Task API

Tilgangur: Stofna og vinna skilaboð í Cloud Event samstillt (bein vinnsla).

Endapunktsupplýsingar:

• Einingaheiti: task
• Einingasettaheiti: tasks
• Grunnslóð: /api/origo/cloudEvent/v1.0/tasks
• Vinnsluháttur: Samstilltur (skilaboð eru unnin samstundis við stofnun)

Reitir: Sömu reitir og Queue API. lcid er ekki stutt í Task API — notaðu Queue API fyrir tungumálsstillt svör.

Studdar aðgerðir:

POST — Stofna og vinna verk

Stofnar ný skilaboð og vinnur þau samstundis. Svarið mun innihalda niðurhalsslóð að svarsgögnunum í data reitnum.

Dæmi um beiðnisniðmát:

{
  "specversion": "1.0",
  "type": "Help.Fields.Get",
  "source": "MyIntegrationApp v1.0",
  "subject": "Customer",
  "datacontenttype": "application/json",
  "data": "{\"tableName\":\"Customer\"}"
}

Skilaboðategundir

Cloud Events-endingurinn styður eftirfarandi skilaboðategundir. Allar innbyggðar skilaboðategundir krefjast JSON-sniðs í data reitnum.

Stækkunarhæfni: Þennan ending má framlengja með sérsniðnum útfærslum fyrir fleiri skilaboðategundir með því að útfæra Cloud Event Msg Interface.

Yfirlit yfir allar skilaboðategundir

Viðburðir og vefkrókar

Cloud Events-endingurinn veitir ytri viðskiptaviðburði sem gera ytri kerfum kleift að fá vefkrókstilkynningar þegar skilaboð líkja eða mistakast við vinnslu. Þetta eyðir þörfina fyrir samfellda könnun og gerir kleift að nota sanna viðburðsdrifna skipan.

Vefkrókstilkynningar

Viðburðamynstur: Lágmarks-tilkynning + API-sæki

1. Ytri kerfi sendir skilaboð í Queue API eða Task API
2. Business Central vinnur skilaboðin ósamstillt (Queue API) eða samstillt (Task API)
3. Þegar vinnslu er lokið eða mistakast, heldur BC uppi ytri viðskiptaviðburðinum
4. Áskrifaðir endapunktar fá lágmarkstilkynningu (MessageId, MessageType, Timestamp)
5. Ytri kerfi kallar á Data API með MessageId til að sækja fullt svar

Tiltækir viðburðir

Uppsetning

Stilltu vefkrókáskriftir í gegnum Event Subscriptions síðu í Business Central:

1. Farðu í Event Subscriptions
2. Stofnaðu nýja áskrift
3. Veldu viðburð: CloudEventMessageCompleted eða CloudEventMessageFailed
4. Stilltu Event Category: "Origo Cloud Event"
5. Stilltu endapunktsslóð og auðkenningu
6. Virkjaðu áskrift

Nákvæm skjöl um vefkrók stillingar, öryggissjónarmiðir og kóðadæmi er að finna í: Events_and_Webhooks.md

Auðkenning

Allir API-endapunktar krefjast auðkenningar með OAuth 2.0 eða Basic Authentication eins og stillt er í Business Central.

Nauðsynlegar heimildir:

• Notendur verða að hafa viðeigandi heimildir skilgreindar í Cloud Events Full heimildarsetti.

Gagnaeinangrun — Entra-forritamarkur

Allir Cloud Events-endapunktar (/tasks, /queues, /responses, /requests) framfylgja strangri gagnaeinangrun á Entra-forritastigi.

Hvert svar er sjálfkrafa síað á þjóni að færslum þar sem SystemCreatedBy = UserSecurityId(). UserSecurityId() í Business Central leysist í Object ID Entra-forritsins (Client ID) sem auðkenndi beiðnina.

Afleiðingar:

Þessi einangrun er skilyrðislaus — hana er ekki hægt að sniðganga með OData síum, admin-skilríkjum eða öðrum meðulum.

Notkunardæmi

Dæmi 1: Sækja lista yfir töflur (samstillt)

Beiðni:

POST /api/origo/cloudEvent/v1.0/tasks
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "datacontenttype": "application/json",
  "data": "{}"
}

Svar:

{
  "specversion": "1.0",
  "type": "Help.Tables.Get",
  "source": "MyIntegrationApp v1.0",
  "id": "12345678-1234-1234-1234-123456789abc",
  "time": "2026-02-19T10:30:00Z",
  "datacontenttype": "text/json",
  "data": "/api/origo/cloudEvent/v1.0/responses(12345678-1234-1234-1234-123456789abc)"
}

Dæmi 2: Sækja reitarlýsigögn töflu (ósamstillt)

Skref 1: Setja í biðröð

POST /api/origo/cloudEvent/v1.0/queues
Content-Type: application/json

{
  "specversion": "1.0",
  "type": "Help.Fields.Get",
  "subject": "Customer",
  "source": "MyIntegrationApp v1.0",
  "datacontenttype": "application/json",
  "data": "{\"tableName\":\"Customer\"}"
}

Skref 2a: Valinn — Kanna stöðu (könnun)

POST /api/origo/cloudEvent/v1.0/queues('{message-id}')/Microsoft.NAV.GetStatus

Skref 2b: Ráðlægt — Vefkrókstilkynning

Gerast áskrifandi að CloudEventMessageCompleted viðburðinum og fáðu sjálfvirka tilkynningu:

{
  "MessageId": "{message-id}",
  "MessageType": "Help.Fields.Get",
  "ResponseContentLink": "/api/origo/cloudEvent/v1.0/responses({message-id})/data",
  "Timestamp": "2026-03-08T14:30:22Z"
}

Skref 3: Sækja niðurstöður

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

Tengd skjöl

• Data_Message_Types.md: Gagnaðgerðir til að sækja og uppfæra færslur
• Metadata_Message_Types.md: Uppbyggingaruppgötvun og API-lýsigögn
• Sales_Message_Types.md: Viðskiptaaðgerðir fyrir sölu, viðskiptavini og vörur
• Purchase_Message_Types.md: Viðskiptaaðgerðir fyrir innkaupapantanir
• Finance_Message_Types.md: Fjárhagsðgerðir fyrir bókhaldslotubækur og fastafjármunadagbækur
• Inventory_Message_Types.md: Vörudagbókargerðir (uppsetning, sannvörðun, bókun)
• Projects_Message_Types.md: Verkefnadagbókargerðir (uppsetning, sannvörðun, bókun)
• Resources_Message_Types.md: Aðfangadagbókargerðir (uppsetning, sannvörðun, bókun)
• IncomingDocument_Message_Types.md: Aðgerðir fyrir innkomandi skjöl
• Memory_Message_Types.md: Minnisaðgerðir á fyrirtækja- og notandasvæði
• Events_and_Webhooks.md: Vefkrókar og ytri viðskiptaviðburðir
• Setup_Reference.md: Uppsetningarhandbók og útfærsluval
• Field_Access_Restrictions.md: Reitarsniðangursheimildir og uppsetning

© Origo – Cloud Events Base Extension