Työtilan Admin API:n endpoint-pyynnöt ja -vastaukset

Tämä on jokaisen /v2/admin-endpointin pyyntö-/vastausviite. Todennus, idempotenssi, pyyntörajoitukset, tunnusten luonti ja käyttöalueiden merkitykset dokumentoidaan kohdassa Työtilan Admin API. Uudelleenkäytettävät kenttätyypit ja esimerkit ovat kohdassa Skeemat ja esimerkit. Lue jokainen endpoint-rivi yhdessä Vastaus- ja virhesopimuksen kanssa, joka luettelee kaikki mahdolliset yhteiset ja endpoint-kohtaiset epäonnistumisrungot.

Yhteinen sopimus

Jokainen polku alkaa käyttöönotetusta app-api-alkuperästä. Työtila johdetaan yksinomaan todennetusta tunnuksesta; asiakkaat eivät saa lähettää cpoId. Kaikki dokumentoidut resurssipolkujen :...Id-arvot ovat positiivisia desimaalikokonaislukuja. Jokainen pyyntö edellyttää täsmälleen yhtä:

Authorization: Bearer <workspace-access-token>

JSON-rungolla esitetyt pyynnöt edellyttävät Content-Type: application/json. Kaikki muutokset edellyttävät Idempotency-Key (POST, PUT, PATCH ja DELETE), mukaan lukien POST /v2/admin/reports/send; ellei rivillä toisin mainita, onnistumisen sisältötyyppi on application/json, JSON-päiväykset ovat RFC 3339 -merkkijonoja ja numerot JSON-numeroita.

Jokainen pyyntö voi sisältää X-Request-Id ja X-Error-Format: envelope; katso Vastaus- ja virhesopimus. Nämä otsakkeet eivät muuta onnistumisskeemoja.

Alla käytetty merkintätapa:

• none tarkoittaa, ettei pyynnöllä ole runkoa. JSON-rungon dokumentoiva DELETE edellyttää silti sitä runkoa.
• ? merkitsee valinnaista ominaisuutta tai kyselyparametria.
• T | null tarkoittaa, että ominaisuus on mukana ja sallii null-arvon.
• 204 empty tarkoittaa, ettei vastauksella ole runkoa.
• CursorPage<T> tarkoittaa { items: T[], nextCursor: number|string|null }, paitsi kun rivi nimeää nimenomaisesti page- tai pagination-objektin.
• Kaikki puuttuvat sisäkkäiset resurssit, myös toisen työtilan tunnisteet, käyttävät 404 { "error": "Workspace resource not found", "code": "RESOURCE_NOT_FOUND" }, ellei toiminnossa dokumentoida tarkempaa ristiriitaa.

Yhteiset pyyntöskeemat

Työtilan ja kohteen syötteet

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
}

Tehonhallinnan syöte

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
}

Laturien syötteet

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

Raporttisyötteet

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

Raporttijaksojen on täytettävä from < to, eivätkä ne saa ylittää 90 päivää. Jos ne puuttuvat, käytetään viimeisintä 90 päivän jaksoa. userId ja anonymous=true sulkevat toisensa pois. Ajastetut viennit korvaavat väliin jääneen UTC-minuutin ja käyttävät rajattuja uusintayrityksiä (5/10 minuutin viive, 30 minuutin vanhentuneen varauksen vuokra, kolme yritystä).

Tariffisyötteet

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 }

Latausprofiilien syötteet

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 }

Käyttäjäsyötteet

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 }

Rajaa luotaessa vähintään toisen arvoista energyValue tai timeValue on oltava nollaa suurempi. Sähköposteista poistetaan reunavälit ja ne muutetaan pieniksi kirjaimiksi. RFID-UID:t hyväksytään vain kirjoituksissa ja peitetään lukuvastauksissa.

Vastaus-DTO:iden yhteenveto

Endpoint-taulukot näyttävät kaikki ylimmän tason vastauskääreet. Tässä ovat niiden tärkeimmät uudelleenkäytettävät DTO:t:

Luettelo-/tietoreitit palauttavat hakuobjekteja kelvollisten tunnisteiden löytämiseksi. Käsittele tuntemattomia lisäkenttiä tulevaisuuteen yhteensopivina ja haarauta vain dokumentoitujen vakaiden kenttien ja virhekoodien perusteella.

Työtilaendpointit

Kohde- ja tehonhallintaendpointit

Laturien endpointit

Raporttien endpointit

Tariffiendpointit

TariffAssignment sisältää id, chargerId, connectorId, turvallisen tariffi-/valuuttayhteenvedon, createdAt ja updatedAt.

Latausprofiilien endpointit

ProfileAssignment sisältää määritystunnisteen, laturin/liittimen tunnisteet ja turvallisen profiiliyhteenvedon. OCPP-tulosobjektit näyttävät vakaat pyyntö-/tilatiedot mutta eivät koskaan tunnistetietoja.

Käyttäjä-, RFID-, käyttöoikeus-, raja- ja paikalliskäyttäjäendpointit

Tagless-järjestelmäkäyttäjä on suojattu näiltä toiminnoilta. Kutsusähköpostin virheet palauttavat turvallisen toimitustilan paljastamatta SMTP-tietoja; kutsuja voi yrittää uudelleen, kun emailRetryReady on true.

Binäärivastaukset

Kaksi endpoint-ryhmää ei palauta JSONia onnistuessaan:

Binääristen endpointien virheet ovat silti JSONia.