Tööruumi Admin API endpointide päringud ja vastused

See on iga /v2/admin endpointi päringu/vastuse viide. Autentimist, idempotentsust, päringupiiranguid, pääsutõendite loomist ja pääsuulatuste semantikat kirjeldab Tööruumi Admin API. Korduvkasutatavad väljatüübid ja näited on Skeemides ja näidetes. Lugege iga endpointi rida koos Vastuste ja vigade lepinguga, mis loetleb kõik ühised ja endpointipõhised ebaedukad vastusesisud.

Ühine leping

Iga tee algab juurutatud app-api päritoluga. Tööruum saadakse ainult autenditud pääsutõendist; kliendid ei tohi saata cpoId. Kõik dokumenteeritud :...Id ressursitee väärtused on positiivsed kümnendtäisarvud. Iga päring vajab täpselt üht:

Authorization: Bearer <workspace-access-token>

JSON-sisuga näidatud päringud nõuavad Content-Type: application/json. Kõik muudatused nõuavad Idempotency-Key (POST, PUT, PATCH ja DELETE), ka POST /v2/admin/reports/send; kui rida ei ütle teisiti, on eduka vastuse sisutüüp application/json, JSON-kuupäevad on RFC 3339 stringid ja arvud JSON-arvud.

Iga päring võib sisaldada X-Request-Id ja X-Error-Format: envelope; vt Vastuste ja vigade leping. Need päised ei muuda eduskeeme.

Allpool kasutatud tähistus:

• none tähendab päringusisu puudumist. DELETE, mis dokumenteerib JSON-sisu, nõuab seda endiselt.
• ? tähistab valikulist omadust või päringuparameetrit.
• T | null tähendab, et omadus on olemas ja lubab nulli.
• 204 empty tähendab vastusesisu puudumist.
• CursorPage<T> tähendab { items: T[], nextCursor: number|string|null }, välja arvatud juhul, kui rida nimetab selgelt page või pagination objekti.
• Kõik puuduvad pesastatud ressursid, ka teise tööruumi ID-d, kasutavad 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, kui funktsioon ei dokumenteeri täpsemat konflikti.

Ühised päringuskeemid

Tööruumi ja asukoha sisendid

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
}

Võimsushalduse sisend

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
}

Laadija sisendid

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

Aruannete sisendid

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

Aruandevahemikud peavad vastama from < to ega tohi ületada 90 päeva. Puudumisel kasutatakse viimast 90 päeva. userId ja anonymous=true on teineteist välistavad. Ajastatud ekspordid teevad vahele jäänud UTC-minuti tasa ning kasutavad piiratud korduskatseid (5/10 minuti viivitus, aegunud hõive 30 minuti liising, kolm katset).

Tariifi sisendid

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 }

Laadimisprofiilide sisendid

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 }

Kasutaja sisendid

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 }

Piirangu loomisel peab vähemalt üks väärtustest energyValue või timeValue olema nullist suurem. E-posti aadresside ääretühikud eemaldatakse ja tähed tehakse väikseks. RFID UID-sid aktsepteeritakse vaid kirjutamisel ja need maskeeritakse lugemisvastustes.

Vastuse DTO kokkuvõte

Endpointide tabelid näitavad kõiki ülataseme vastuseümbrisi. Need on nende peamised korduvkasutatavad DTO-d:

Loendi-/detailimarsruudid tagastavad teatmeobjekte, et kliendid leiaksid kehtivad ID-d. Käsitlege lisatud tundmatuid välju tulevikuga ühilduvatena ja harunege ainult dokumenteeritud stabiilsete väljade ja veakoodide alusel.

Tööruumi endpointid

Asukoha ja võimsushalduse endpointid

Laadija endpointid

Aruannete endpointid

Tariifi endpointid

TariffAssignment sisaldab id, chargerId, connectorId, ohutut tariifi/valuuta kokkuvõtet, createdAt ja updatedAt.

Laadimisprofiilide endpointid

ProfileAssignment sisaldab määrangu ID-d, laadija/pistiku ID-sid ja ohutut profiilikokkuvõtet. OCPP tulemuseobjektid avaldavad stabiilset päringu-/olekuteavet, mitte kunagi autentimisandmeid.

Kasutaja, RFID, juurdepääsu, piirangu ja kohaliku kasutaja endpointid

Taglessi süsteemikasutaja on nende toimingute eest kaitstud. Kutse-e-kirja tõrked tagastavad ohutu kohaletoimetamisoleku SMTP üksikasju avaldamata; klient võib korrata, kui emailRetryReady on true.

Kahendvastused

Kaks endpointide rühma ei tagasta õnnestumisel JSON-i:

Kahendendpointide vead on endiselt JSON.