Darbo srities administravimo API galinių taškų užklausos ir atsakymai

Tai kiekvieno /v2/admin galinio taško užklausų ir atsakymų žinynas. Autentifikavimas, idempotentiškumas, užklausų dažnio ribos, prieigos raktų kūrimas ir prieigos sričių reikšmė aprašyti Darbo srities administravimo API. Pakartotinai naudojami laukų tipai ir pavyzdžiai pateikti Schemose ir pavyzdžiuose. Kiekvieną galinio taško eilutę skaitykite kartu su Atsakymų ir klaidų sutartimi, kurioje išvardytas visas galimas bendras ir konkrečiam taškui būdingas nesėkmingų atsakymų turinys.

Bendra sutartis

Kiekvienas kelias prasideda įdiegtos app-api paslaugos pradžios adresu. Darbo sritis nustatoma tik iš autentifikuoto prieigos rakto; klientai negali siųsti cpoId. Visos dokumentuotos :...Id išteklių kelio reikšmės yra teigiami dešimtainiai sveikieji skaičiai. Kiekvienai užklausai reikia tiksliai vienos:

Authorization: Bearer <workspace-access-token>

Užklausoms su nurodytu JSON turiniu reikia Content-Type: application/json. Visoms duomenų keitimo operacijoms reikia Idempotency-Key (POST, PUT, PATCH ir DELETE), įskaitant POST /v2/admin/reports/send; jei eilutėje nenurodyta kitaip, sėkmingo atsakymo turinio tipas yra application/json, JSON datos yra RFC 3339 eilutės, o skaičiai — JSON skaičiai.

Kiekvienoje užklausoje gali būti X-Request-Id ir X-Error-Format: envelope; žr. Atsakymų ir klaidų sutartį. Šios antraštės nekeičia sėkmingų atsakymų schemų.

Toliau naudojami žymėjimai:

• none reiškia, kad užklausos turinio nėra. DELETE, kuriam dokumentuotas JSON turinys, vis tiek jo reikalauja.
• ? žymi neprivalomą savybę arba užklausos parametrą.
• T | null reiškia, kad savybė yra ir gali būti null.
• 204 empty reiškia, kad atsakymo turinio nėra.
• CursorPage<T> reiškia { items: T[], nextCursor: number|string|null }, išskyrus atvejus, kai eilutėje aiškiai įvardytas page arba pagination objektas.
• Visiems nerastiems įdėtiesiems ištekliams, įskaitant kitos darbo srities ID, naudojamas 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, nebent funkcija dokumentuoja konkretesnį konfliktą.

Bendros užklausų schemos

Darbo srities ir vietos įvesties duomenys

WorkspacePatch = {
  name?: string(1..100), email?: email|null, website?: string|null,
  addressLine1?: string|null, addressLine2?: string|null,
  postalCode?: string|null, city?: string|null, state?: string|null,
  countryId?: positive integer
} // at least one property

SiteInput = {
  name: string(1..255), description?: string|null = null,
  addressLine1?: string|null = null, addressLine2?: string|null = null,
  postalCode?: string|null = null, city?: string|null = null, state?: string|null = null,
  countryId: positive integer, timezoneId: positive integer,
  latitude?: number[-90,90]|null = null, longitude?: number[-180,180]|null = null
}

Galios valdymo įvestis

PowerConfigurationInput = { pools: PowerPoolInput[0..200] }
PowerPoolInput = {
  id?: positive integer|null, name?: string(0..255),
  limit: integer[0,100000000], meterSources?: ExternalMeterInput[0..16],
  children?: (PowerPoolInput | ChargerPoolChild)[0..1000]
}
ChargerPoolChild = { chargepointId: positive integer, priority?: integer[-1000000,1000000] }
ExternalMeterInput = {
  id?: positive integer|null, sourceId?: positive integer|null,
  provider?: "perific", name?: string(0..255), externalId: string(1..80),
  measurementMode?: "available_headroom"|"external_non_ev_load_only"|"total_site_load_including_ev",
  valueMode?: "perific_relative"|"perific_direct"|"perific_meter",
  reserveA?: integer[0,100000], offlineSafeA?: integer[0,100000],
  ttlSeconds?: integer[30,86400], enabled?: boolean
}

Įkroviklio įvesties duomenys

ChargerCreate = { name: string(1..40), identifier: string(1..40), password?: string(0..40) = "", siteId: positive integer }
ChargerPatch = {
  name?: string(1..40), siteId?: positive integer, invertedRfid?: boolean,
  smartMode?: integer[0,3], automationDisabled?: boolean
} // at least one
ConnectorPatch = {
  connectorFormatId: positive integer, connectorTypeId: positive integer,
  powerTypeId: positive integer, maxVoltage: integer[1,10000],
  maxAmperage: integer[1,10000], maxElectricPower: integer[1,100000000]
}

Ataskaitų įvesties duomenys

ReportFilters = {
  from?: RFC3339, to?: RFC3339, siteId?: positive integer,
  chargerId?: positive integer, userId?: positive integer,
  anonymous?: true|false|1|0, active?: true|false|1|0
}
ReportScheduleInput = {
  enabled: boolean, recipientEmail: email(max 255; may be empty only when disabled), format: "csv"|"pdf",
  sendDay: integer[1,28], sendTime: UTC "HH:mm"
}

Ataskaitų intervalai turi atitikti from < to ir negali viršyti 90 dienų. Nepateikus intervalo naudojamos paskutinės 90 dienų. userId ir anonymous=true negali būti naudojami kartu. Suplanuoti eksportai kompensuoja praleistą UTC minutę ir naudoja ribotus pakartojimus (5 / 10 minučių atidėjimas, 30 minučių pasenusios užduoties rezervacijos laikas, trys bandymai).

Tarifų įvesties duomenys

TariffInput = {
  name: string(1..64),
  exactly one of currencyId: positive integer, currencyCode: 3 letters, currency: 3 letters,
  biddingZoneId?: positive integer|null, tax?: finite number
}
TariffComponentInput = {
  typeId: positive integer, seasonId: positive integer, priority?: finite number,
  price: finite number, validFromMonth?: finite number, validToMonth?: finite number,
  validFromWeekDay?: finite number, validToWeekDay?: finite number,
  validFromHour?: finite number, validToHour?: finite number
}
TariffAssignmentCreateInput = { tariffId: positive integer, connectorId?: nonnegative integer }
TariffAssignmentUpdateInput = { tariffId: positive integer, connectorId: positive integer }

Įkrovimo profilių įvesties duomenys

ChargingProfileInput = {
  label: string(1..40), locationId: positive integer, stackLevel: nonnegative number,
  purposeId: positive integer, kindId: positive integer,
  recurrencyKindId?: positive integer|null, validFrom?: RFC3339|null,
  validTo?: RFC3339|null, startSchedule?: RFC3339|null,
  rateUnitId: positive integer, minChargingRate?: nonnegative number|null
}
ChargingProfileCreate = ChargingProfileInput & { schedule?: SchedulePeriod[0..256] }
SchedulePeriod = { startPeriod: nonnegative number, limit: nonnegative number, numberOfPhases?: positive integer|null }
ChargingScheduleInput = { rateUnitId: positive integer, periods: SchedulePeriod[1..256] }
ProfileAssignmentInput = { profileId: positive integer, connectorId?: nonnegative integer }

Naudotojų įvesties duomenys

UserCreate = { email: email(max 255), name: string(1..255) }
InvitationInput = {
  email: email, name?: string|null, rfid?: string|null,
  allChargers?: boolean, chargerIds?: unique positive integer[0..500]
} // chargerIds must be non-empty unless allChargers=true
AccessInput = { allChargers?: boolean, chargerIds?: unique positive integer[0..500] }
LimitCreate = { limitTypeId: positive integer, energyValue?: nonnegative integer = 0, timeValue?: nonnegative integer = 0 }
LimitPatch = { limitTypeId?: positive integer, energyValue?: nonnegative integer, timeValue?: nonnegative integer }

Kuriant ribą bent viena iš energyValue arba timeValue reikšmių turi būti didesnė už nulį. Iš el. pašto adresų pašalinami kraštiniai tarpai, o raidės pakeičiamos mažosiomis. RFID UID priimami tik rašymo operacijose ir užmaskuojami skaitymo atsakymuose.

Atsakymų DTO santrauka

Galinių taškų lentelėse parodyti visi aukščiausio lygio atsakymų apvalkalai. Tai pagrindiniai pakartotinai naudojami DTO šiuose apvalkaluose:

Žinyno objektai grąžinami sąrašų ir išsamios informacijos maršrutais, kad kviečiančiosios programos galėtų rasti tinkamus ID. Nežinomus pridėtus laukus laikykite su būsimomis versijomis suderinamais plėtiniais, o sprendimus grįskite tik dokumentuotais stabiliais laukais ir klaidų kodais.

Darbo srities galiniai taškai

Vietų ir galios valdymo galiniai taškai

Įkroviklių galiniai taškai

Ataskaitų galiniai taškai

Tarifų galiniai taškai

TariffAssignment turi id, chargerId, connectorId, saugią tarifo / valiutos santrauką, createdAt ir updatedAt.

Įkrovimo profilių galiniai taškai

ProfileAssignment turi priskyrimo ID, įkroviklio / jungties ID ir saugią profilio santrauką. OCPP rezultatų objektai pateikia stabilią užklausos / būsenos informaciją ir niekada neteikia prisijungimo duomenų.

Naudotojų, RFID, prieigos, ribų ir vietinių naudotojų galiniai taškai

„Tagless“ sistemos naudotojas apsaugotas nuo šių operacijų. Nepavykus išsiųsti kvietimo el. paštu grąžinama saugi pristatymo būsena, neatskleidžiant SMTP duomenų; kviečiančiosios programos gali bandyti dar kartą, kai emailRetryReady yra true.

Dvejetainiai atsakymai

Dvi galinių taškų grupės sėkmės atveju negrąžina JSON:

Dvejetainių galinių taškų klaidos vis tiek yra JSON formato.