Darbvietas administrēšanas API galapunktu pieprasījumi un atbildes

Šī ir katra /v2/admin galapunkta pieprasījumu/atbilžu uzziņa. Autentifikācija, idempotence, biežuma ierobežojumi, marķieru izveide un tvērumu nozīme ir dokumentēta Darbvietas administrēšanas API. Atkārtoti lietojamie lauku līmeņa tipi un piemēri ir sadaļā Shēmas un piemēri. Katru galapunkta rindu lasiet kopā ar Atbilžu un kļūdu līgumu, kur uzskaitīts viss iespējamais kopīgo un galapunktam specifisko neveiksmīgo atbilžu saturs.

Kopīgais līgums

Katrs ceļš sākas ar izvietoto app-api izcelsmi. Darbvieta tiek noteikta tikai pēc autentificētā marķiera; klienti nedrīkst sūtīt cpoId. Visas dokumentētās :...Id resursu ceļu vērtības ir pozitīvi decimāli veseli skaitļi. Katrā pieprasījumā nepieciešama tieši viena:

Authorization: Bearer <workspace-access-token>

Pieprasījumiem, kas parādīti ar JSON saturu, nepieciešams Content-Type: application/json. Visām izmaiņām nepieciešams Idempotency-Key (POST, PUT, PATCH un DELETE), tostarp POST /v2/admin/reports/send; ja rindā nav norādīts citādi, veiksmīgās atbildes satura tips ir application/json, JSON datumi ir RFC 3339 virknes, bet skaitļi ir JSON skaitļi.

Katrs pieprasījums var ietvert X-Request-Id un X-Error-Format: envelope; skatiet Atbilžu un kļūdu līgumu. Šīs galvenes nemaina veiksmīgo atbilžu shēmas.

Tālāk izmantotie apzīmējumi:

• none nozīmē, ka nav pieprasījuma satura. DELETE, kam dokumentēts JSON saturs, joprojām prasa šo saturu.
• ? apzīmē neobligātu rekvizītu vai vaicājuma parametru.
• T | null nozīmē, ka rekvizīts ir klātesošs un var būt null.
• 204 empty nozīmē, ka nav atbildes satura.
• CursorPage<T> nozīmē { items: T[], nextCursor: number|string|null }, izņemot gadījumus, kad rinda skaidri nosauc page vai pagination objektu.
• Visos ligzdotu resursu neatrašanas gadījumos, tostarp citas darbvietas ID gadījumā, tiek izmantots 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, ja vien funkcija nedokumentē konkrētāku konfliktu.

Kopīgās pieprasījumu shēmas

Darbvietu un objektu ievaddati

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
}

Jaudas pārvaldības ievaddati

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
}

Lādētāju ievaddati

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

Pārskatu ievaddati

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

Pārskatu diapazoniem jāatbilst from < to, un tie nedrīkst pārsniegt 90 dienas. Ja nav norādīti, tiek izmantotas pēdējās 90 dienas. userId un anonymous=true savstarpēji izslēdzas. Plānotie eksporti atgūst izlaistu UTC minūti un izmanto ierobežotus atkārtotus mēģinājumus (5/10 minūšu aizkave, 30 minūšu novecojušas rezervācijas termiņš, trīs mēģinājumi).

Tarifu ievaddati

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 }

Uzlādes profilu ievaddati

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 }

Lietotāju ievaddati

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 }

Veidojot ierobežojumu, vismaz vienai no energyValue vai timeValue vērtībām jābūt lielākai par nulli. E-pasta adrešu sākuma un beigu atstarpes tiek noņemtas, un adreses tiek pārveidotas uz mazajiem burtiem. RFID UID tiek pieņemti tikai rakstīšanas darbībās un maskēti lasīšanas atbildēs.

Atbilžu DTO kopsavilkums

Galapunktu tabulas rāda katru augstākā līmeņa atbildes ietvaru. Šie ir galvenie atkārtoti lietojamie DTO tajos:

Uzziņu objektus atgriež sarakstu/detaļu maršruti, lai izsaucēji varētu atrast derīgus ID. Nezināmus pievienotus laukus uzskatiet par saderīgiem ar turpmākām versijām un gadījumus atšķiriet tikai pēc dokumentētiem stabiliem laukiem un kļūdu kodiem.

Darbvietu galapunkti

Objektu un jaudas pārvaldības galapunkti

Lādētāju galapunkti

Pārskatu galapunkti

Tarifu galapunkti

TariffAssignment satur id, chargerId, connectorId, drošu tarifa/valūtas kopsavilkumu, createdAt un updatedAt.

Uzlādes profilu galapunkti

ProfileAssignment satur savu piešķīruma ID, lādētāja/pieslēgvietas ID un drošu profila kopsavilkumu. OCPP rezultātu objekti atklāj stabilu pieprasījuma/statusa informāciju, bet nekad piekļuves datus.

Lietotāju, RFID, piekļuves, ierobežojumu un vietējo lietotāju galapunkti

Tagless sistēmas lietotājs ir aizsargāts pret šīm darbībām. Uzaicinājuma e-pasta kļūmes atgriež drošu piegādes stāvokli, neatklājot SMTP detaļas; izsaucēji var atkārtot mēģinājumu, ja emailRetryReady ir patiess.

Bināras atbildes

Divas galapunktu grupas veiksmīgā gadījumā neatgriež JSON:

Bināro galapunktu kļūdas joprojām ir JSON formātā.