Documentation
¶
Overview ¶
Package zeitreihermodels holds the hand-written public data models of the Zeitreiher API, version 1.
Zeitreiher is a read-only API over SAP IS-U EDM profile values (Lastgänge). The contract is the JSON form of the types in this package, pinned by the shared fixtures in testdata/, which the Go and the Python models both parse and round-trip. The gRPC contract lives in proto/zeitreiher/v1.
The package lives at the repository root; its major version follows Go module versioning, so a breaking v2 is the module github.com/hochfrequenz/zeitreiher-models/v2 (spec §3.4).
Nothing in this package is generated. Every type validates itself when it is unmarshalled and refuses to marshal when it is invalid, so a value that leaves or enters a program through these types always satisfies the contract:
- Request timestamps are RFC 3339 with whole seconds and an explicit offset (Z or ±hh:mm). Timestamps without an offset and the "unknown offset" -00:00 are rejected.
- Response timestamps are RFC 3339 with whole seconds in UTC (Z).
- Intervals are half-open: [from, to), and from must be before to.
- Values are decimal strings, already scaled, in shortest canonical form ("160", "0.022"; never "160.0"), never JSON numbers.
- Error codes are strict on write, lenient on read: unknown snake_case codes parse, only the public codes are written.
- Requests reject unknown keys; responses ignore them, so additive server changes do not break older clients.
Index ¶
- Constants
- Variables
- func IsUnitCode(s string) bool
- func MarshalRecord(rec Record) ([]byte, error)
- func ReadRecords(r io.Reader) iter.Seq2[Record, error]
- func WriteRecord(w io.Writer, rec Record) error
- type Assignment
- type Caps
- type Decimal
- type EndRecord
- type ErrorDetail
- type ErrorEnvelope
- type ErrorRecord
- type InactiveObjects
- type QueryRequest
- type Record
- type RecordErrorCode
- type RequestErrorCode
- type ResolveRequest
- type ResolveResponse
- type ResolveResult
- type ResultError
- type Selector
- type SeriesRecord
- type SystemInfo
- type ValueRecord
- type Version
- type VersionSelector
- type VersionedAssignment
- type VersionsRequest
- type VersionsResponse
- type VersionsResult
- type WindowRequest
Constants ¶
const ( // RecordTypeSeries opens a series: one profile assignment of one selector, cut to the request window. RecordTypeSeries = "series" // RecordTypeValue is one value of a series for a half-open interval [from, to). RecordTypeValue = "value" // RecordTypeError is a per-selector or per-assignment problem; the stream continues. RecordTypeError = "error" // RecordTypeEnd closes a successful response; a response without it is incomplete and a failure. RecordTypeEnd = "end" )
Record types, the value of the "type" key of every NDJSON line.
const ( // SelectorByProfile selects a profile by its number. SelectorByProfile = "profile" // SelectorByMaLo selects the profiles assigned to a market location (11 digits). SelectorByMaLo = "malo" )
Selector kinds known to every Zeitreiher installation. Any other kind is a custom selector that a customer resolver implements.
Variables ¶
var ErrMissingEnd = errors.New("response stream does not end with an end record")
ErrMissingEnd is returned by ReadStream when a response does not end with exactly one end record. Such a response was cut off and must be treated as a failure (spec §4.3).
Functions ¶
func IsUnitCode ¶ added in v0.4.0
IsUnitCode reports whether s is a canonical unit code: a UN/ECE Recommendation 20 code such as "KWH", "MWH" or "K3" ("K3" = kvarh), that is 2 or 3 upper-case ASCII letters or digits, strict. It is the rule the models apply to unit in requests, series records and assignments, exported so that consumers need not copy the pattern. The Python counterpart is zeitreiher_models.is_unit_code. Whether a well-formed code is supported is the server's decision (an unknown code is a 400).
func MarshalRecord ¶
MarshalRecord validates rec and returns its JSON form without a trailing newline.
func ReadRecords ¶
ReadRecords yields the records of an NDJSON stream. Every line must hold one record; the final newline is optional. Blank lines and carriage returns are errors. Iteration stops after the first error. ReadRecords does not check for the end record; use ReadStream for complete responses.
Types ¶
type Assignment ¶
type Assignment struct {
// Profile is the profile number without leading zeros.
Profile string
// Role is the profile role of the assignment (SAP EPROFASS role, e.g. "0001"; any non-empty text),
// or nil when the assignment was not resolved through a role (e.g. by: profile).
Role *string
// From is the start of the assignment (inclusive), cut to the request window; set together with To.
From *time.Time
// To is the end of the assignment (exclusive), cut to the request window.
To *time.Time
// Unit is the canonical unit code (UN/ECE Rec. 20, e.g. "KWH") of the profile's values, or nil when the
// SAP unit has no mapping.
Unit *string
// UnitRaw is the SAP unit key (T006 MSEHI) as SAP delivers it, mapped or not: any non-empty text of at
// most 30 characters without control characters.
UnitRaw string
// Error is the assignment-level error; nil for a usable assignment.
Error *ResultError
}
Assignment is one profile assignment of a resolve result (spec §4.4). Either From and To are set (the assignment, cut to the request window) or Error is set (e.g. access_denied); an assignment with an error may still carry its window.
Role, Unit and UnitRaw describe the profile of the assignment exactly like the fields of the same name in a series record. Without an Error, Role and Unit are always written (null when nil) and UnitRaw is required. With an Error they may be left out: nil Role, nil Unit and an empty UnitRaw are then omitted.
func (Assignment) MarshalJSON ¶
func (a Assignment) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the assignment.
func (*Assignment) UnmarshalJSON ¶
func (a *Assignment) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the assignment; unknown keys (such as versions) are ignored.
type Caps ¶ added in v0.2.0
type Caps struct {
// MaxWindowSeconds is the longest window in seconds of one internal SAP values call; the service splits
// longer query windows (at least 1).
MaxWindowSeconds int64
// MaxValues is the highest number of values of one internal SAP values call (at least 1).
MaxValues int64
// MaxResolveWindowSeconds is the longest request window in seconds the service accepts for query, resolve
// and versions; a longer window is a 400 invalid_request (at least 1).
MaxResolveWindowSeconds int64
}
Caps are the limits of the service (spec section 3.1), reported so that clients know how it works. MaxWindowSeconds and MaxValues bound one internal SAP values call; the service splits a query window accordingly. MaxResolveWindowSeconds is the longest request window the service accepts for query, resolve and versions; longer windows are 400 invalid_request. Versions and resolve are not split and have no value cap. The internal window_too_large answer of SAP never reaches public clients.
func (Caps) MarshalJSON ¶ added in v0.2.0
MarshalJSON validates and writes the caps.
func (*Caps) UnmarshalJSON ¶ added in v0.2.0
UnmarshalJSON parses and validates the caps; unknown keys are ignored.
type Decimal ¶
type Decimal string
Decimal is an already-scaled decimal number in its shortest canonical string form, e.g. "160", "0.022", "25.25" or "-3.5".
Decimal is an already-scaled decimal value, a string on the wire. Values are strings on the wire so that no client loses precision by parsing them as floats. The accepted syntax is an optional minus, an integer part without leading zeros and an optional fractional part without trailing zeros: ^-?(0|[1-9][0-9]*)(\.[0-9]+)?$, and the fraction must not end in 0. Exponents, a plus sign, negative zero, trailing zeros ("160.0", "0.0220") and JSON numbers are rejected: after parsing, 160.0 and 160 are the same number, so the wire carries one spelling.
func (Decimal) MarshalJSON ¶
MarshalJSON writes d as a JSON string after validating it.
func (*Decimal) UnmarshalJSON ¶
UnmarshalJSON accepts a JSON string with a valid decimal only.
type EndRecord ¶
type EndRecord struct {
// Series, Values and Errors count the series, value and error records on this page only (not
// the whole result). A series record re-sent at the start of a continuation page counts again.
Series, Values, Errors int
// Next is the cursor for the next page, or nil when the result is complete.
Next *string
}
EndRecord closes a successful response. A response without an end record is incomplete and must be treated as a failure.
func (*EndRecord) MarshalJSON ¶
MarshalJSON validates and writes the record; a nil Next is written as null.
func (*EndRecord) UnmarshalJSON ¶
UnmarshalJSON parses and validates the record.
type ErrorDetail ¶
type ErrorDetail struct {
// Code is stable and machine-readable; clients switch on it, never on Message.
Code RequestErrorCode `json:"code"`
// Message is a human-readable explanation.
Message string `json:"message"`
// RequestID correlates the response with server logs; empty when unknown (omitted on the wire).
RequestID string `json:"request_id,omitempty"`
}
ErrorDetail is the content of an ErrorEnvelope.
func (*ErrorDetail) UnmarshalJSON ¶
func (d *ErrorDetail) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules of the detail.
type ErrorEnvelope ¶
type ErrorEnvelope struct {
// Error is the error code, message and optional request id.
Error ErrorDetail `json:"error"`
}
ErrorEnvelope is the body of every failed (non-2xx) HTTP response: {"error":{"code":"…","message":"…","request_id":"…"}}. It has the shape of btpingo.ErrorEnvelope.
func (ErrorEnvelope) MarshalJSON ¶
func (e ErrorEnvelope) MarshalJSON() ([]byte, error)
MarshalJSON validates before writing.
func (*ErrorEnvelope) UnmarshalJSON ¶
func (e *ErrorEnvelope) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules of the envelope.
func (ErrorEnvelope) Validate ¶
func (e ErrorEnvelope) Validate() error
Validate checks the envelope.
type ErrorRecord ¶
type ErrorRecord struct {
// Selector is the index of the request selector the problem belongs to.
Selector int
// Select echoes the request selector.
Select Selector
// Profile is set where the problem concerns one profile assignment; empty otherwise.
Profile string
// Code says what went wrong; see the RecordError* constants.
Code RecordErrorCode
}
ErrorRecord reports a per-selector or per-assignment problem; the stream continues.
func (*ErrorRecord) MarshalJSON ¶
func (r *ErrorRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record; an empty Profile is omitted.
func (*ErrorRecord) RecordType ¶
func (*ErrorRecord) RecordType() string
RecordType returns "error".
func (*ErrorRecord) UnmarshalJSON ¶
func (r *ErrorRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type InactiveObjects ¶ added in v0.6.0
type InactiveObjects struct {
// Available says whether the ABAP backend could determine the inactive objects.
Available bool
// Count is the number of inactive objects; set exactly when Available (equals len(Names)).
Count *int64
// Names are the inactive object names; nil or empty is written as [] when Available, and must be nil
// otherwise.
Names []string
// Reason says why the inactive objects are unknown; set exactly when not Available (non-empty text).
Reason string
}
InactiveObjects reports the inactive ABAP objects of the package, or why that is unknown. Available true: Count and Names are set (Count equals len(Names)) and Reason is empty. Available false: Reason is set and Count and Names are not.
func (InactiveObjects) MarshalJSON ¶ added in v0.6.0
func (o InactiveObjects) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the report.
func (*InactiveObjects) UnmarshalJSON ¶ added in v0.6.0
func (o *InactiveObjects) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the report; unknown keys are ignored.
func (InactiveObjects) Validate ¶ added in v0.6.0
func (o InactiveObjects) Validate() error
Validate checks the inactive-objects report.
type QueryRequest ¶
type QueryRequest struct {
// Select lists one or more selectors; results refer to them by index.
Select []Selector
// From and To bound the half-open window [From, To). Their offsets are kept on the wire.
From, To time.Time
// Version is optional; nil means the current values.
Version *VersionSelector
// Interval is optional, e.g. "PT15M"; empty means the profile's own interval.
Interval string
// Unit is optional, a canonical unit code (UN/ECE Rec. 20) such as "KWH", "MWH" or "K3" ("K3" = kvarh); the server
// maps it to the customer's SAP unit. Empty means the profile's own unit.
Unit string
// Cursor continues a previous response (its end record's next); empty starts at the beginning.
Cursor string
}
QueryRequest is the body of POST /api/v1/series/query (and QUERY /api/v1/series), spec §4.1.
func (QueryRequest) MarshalJSON ¶
func (q QueryRequest) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the request; unset optional fields are omitted.
func (*QueryRequest) UnmarshalJSON ¶
func (q *QueryRequest) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the request. Unknown keys are rejected; null optional fields count as absent.
type Record ¶
type Record interface {
// RecordType returns the value of the "type" key.
RecordType() string
// Validate checks the record.
Validate() error
// contains filtered or unexported methods
}
Record is one line of a query response (NDJSON) and one gRPC Record message. It is one of *SeriesRecord, *ValueRecord, *ErrorRecord or *EndRecord.
func ParseRecord ¶
ParseRecord parses one NDJSON line (without its trailing newline) into a record.
type RecordErrorCode ¶
type RecordErrorCode string
RecordErrorCode is a per-selector or per-assignment error code. It appears in NDJSON error records and in the error objects of resolve/versions results; the rest of the response continues.
const ( // RecordErrorSelectorNotFound is used when the selector matches no business object (e.g. an unknown // market location). RecordErrorSelectorNotFound RecordErrorCode = "selector_not_found" // RecordErrorNoAssignment is used when the selector exists but has no profile assignment in the // request window. RecordErrorNoAssignment RecordErrorCode = "no_assignment" // RecordErrorUnknownSelector is used when the selector kind (by) is not known to this installation. RecordErrorUnknownSelector RecordErrorCode = "unknown_selector" // RecordErrorBadSelector is used when the selector's parameters are not acceptable to its resolver. RecordErrorBadSelector RecordErrorCode = "bad_selector" // RecordErrorAccessDenied is used when the caller is not allowed to read this profile. RecordErrorAccessDenied RecordErrorCode = "access_denied" // RecordErrorProfileNotFound is used when the profile does not exist. RecordErrorProfileNotFound RecordErrorCode = "profile_not_found" // RecordErrorProfileTimeZoneMissing is used when the profile has no time zone, so its values cannot be // read. RecordErrorProfileTimeZoneMissing RecordErrorCode = "profile_time_zone_missing" // RecordErrorIntervalSizeUnsupported is used when the profile's interval size is not supported. RecordErrorIntervalSizeUnsupported RecordErrorCode = "interval_size_unsupported" // RecordErrorWindowUnaligned is used when the request window does not lie on the grid of the profile // and the requested interval (the least common multiple of both interval lengths); the end of the // window must lie on that grid too. RecordErrorWindowUnaligned RecordErrorCode = "window_unaligned" // RecordErrorAssignmentUnaligned is used when the bounds of the profile assignment are not aligned to // the profile's intervals. RecordErrorAssignmentUnaligned RecordErrorCode = "assignment_unaligned" // RecordErrorVersionNotFound is used when the requested version number does not exist for the profile. RecordErrorVersionNotFound RecordErrorCode = "version_not_found" // RecordErrorVersionDeleted is used when the requested {"number": N} names a version that is flagged // as deleted (it is still listed by the versions endpoint, with deleted: true). RecordErrorVersionDeleted RecordErrorCode = "version_deleted" // RecordErrorConversionNotAllowed is used when the requested unit or interval conversion is not // allowed for the profile. RecordErrorConversionNotAllowed RecordErrorCode = "conversion_not_allowed" // RecordErrorAmbiguousLocalTime is used when a local time in the window occurs twice (daylight saving // change) and cannot be mapped to one instant. RecordErrorAmbiguousLocalTime RecordErrorCode = "ambiguous_local_time" // RecordErrorBadiFailed is used when any customer BAdI (spec section 3.2) raised an exception. RecordErrorBadiFailed RecordErrorCode = "badi_failed" // RecordErrorUnitMissing is used when the SAP unit key of the series is empty (or only control characters) and no // canonical code exists, so unit_raw cannot be filled. RecordErrorUnitMissing RecordErrorCode = "unit_missing" )
Record-level error codes (spec §4.3, consolidated list).
func AllRecordErrorCodes ¶
func AllRecordErrorCodes() []RecordErrorCode
AllRecordErrorCodes returns every record-level error code in specification order.
func (RecordErrorCode) IsKnown ¶
func (c RecordErrorCode) IsKnown() bool
IsKnown reports whether c is one of the record-level codes this version of the models knows. Parsing accepts unknown snake_case codes so that a newer server does not break older clients.
func (RecordErrorCode) MarshalJSON ¶
func (c RecordErrorCode) MarshalJSON() ([]byte, error)
MarshalJSON writes only the public codes: error codes are strict on write, lenient on read.
func (*RecordErrorCode) UnmarshalJSON ¶
func (c *RecordErrorCode) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts any snake_case code; use IsKnown to tell known from unknown codes.
func (RecordErrorCode) Validate ¶
func (c RecordErrorCode) Validate() error
Validate checks the code syntax (snake_case). It accepts unknown codes, as parsing does.
type RequestErrorCode ¶
type RequestErrorCode string
RequestErrorCode is a request-level error code. It appears in the error envelope of an HTTP response that failed as a whole (before any NDJSON record was written).
const ( // RequestErrorInvalidRequest is used when the request is invalid: missing offset, fractional seconds, // from not before to, bad selector shape, too many selectors, unsupported interval, unknown unit, // number with interval or unit, or a window longer than the resolve limit. HTTP 400; gRPC // INVALID_ARGUMENT. RequestErrorInvalidRequest RequestErrorCode = "invalid_request" // UNAUTHENTICATED. RequestErrorUnauthorized RequestErrorCode = "unauthorized" // RequestErrorForbidden is used when the caller is authenticated but not allowed to use the API. HTTP // 403; gRPC PERMISSION_DENIED. RequestErrorForbidden RequestErrorCode = "forbidden" // RequestErrorNotFound is used when the route is unknown. HTTP 404; gRPC NOT_FOUND. RequestErrorNotFound RequestErrorCode = "not_found" // RequestErrorMethodNotAllowed is used when the HTTP method is not allowed for the route. HTTP 405; // gRPC UNIMPLEMENTED. RequestErrorMethodNotAllowed RequestErrorCode = "method_not_allowed" // RequestErrorRequestTooLarge is used when the request body exceeds the size limit. HTTP 413; gRPC // RESOURCE_EXHAUSTED. RequestErrorRequestTooLarge RequestErrorCode = "request_too_large" // RequestErrorUpstreamUnreachable is used when the SAP system cannot be reached, or fails in a way the // service cannot pass on, before the first record. HTTP 502; gRPC UNAVAILABLE. RequestErrorUpstreamUnreachable RequestErrorCode = "upstream_unreachable" // RequestErrorInternal is used when the service fails unexpectedly before the first record. HTTP 500; // gRPC INTERNAL. RequestErrorInternal RequestErrorCode = "internal" // RequestErrorCursorInvalid is used when the cursor is malformed or its signature is bad. HTTP 400; // gRPC INVALID_ARGUMENT. RequestErrorCursorInvalid RequestErrorCode = "cursor_invalid" // RequestErrorCursorMismatch is used when the cursor does not match the request. HTTP 400; gRPC // INVALID_ARGUMENT. RequestErrorCursorMismatch RequestErrorCode = "cursor_mismatch" // RequestErrorCursorExpired is used when the cursor has expired. HTTP 400; gRPC INVALID_ARGUMENT. RequestErrorCursorExpired RequestErrorCode = "cursor_expired" // RequestErrorCursorStale is used when the profile assignments changed since the cursor was issued; // restart the query. HTTP 409; gRPC ABORTED. RequestErrorCursorStale RequestErrorCode = "cursor_stale" // RequestErrorUpstreamTimeout is used when the SAP system does not answer in time before the first // record. HTTP 504; gRPC DEADLINE_EXCEEDED. RequestErrorUpstreamTimeout RequestErrorCode = "upstream_timeout" )
Request-level error codes (spec §4.3, consolidated list). The first eight are btpingo's request-level vocabulary (btpingo.ErrorCode in httperr.go), shared by the Hochfrequenz BTP services; the cursor codes and upstream_timeout are Zeitreiher's own.
func AllRequestErrorCodes ¶
func AllRequestErrorCodes() []RequestErrorCode
AllRequestErrorCodes returns every request-level error code in specification order.
func (RequestErrorCode) IsKnown ¶
func (c RequestErrorCode) IsKnown() bool
IsKnown reports whether c is one of the request-level codes this version of the models knows. Parsing accepts unknown snake_case codes so that a newer server does not break older clients.
func (RequestErrorCode) MarshalJSON ¶
func (c RequestErrorCode) MarshalJSON() ([]byte, error)
MarshalJSON writes only the public codes: error codes are strict on write, lenient on read.
func (*RequestErrorCode) UnmarshalJSON ¶
func (c *RequestErrorCode) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts any snake_case code; use IsKnown to tell known from unknown codes.
func (RequestErrorCode) Validate ¶
func (c RequestErrorCode) Validate() error
Validate checks the code syntax (snake_case). It accepts unknown codes, as parsing does.
type ResolveRequest ¶
type ResolveRequest = WindowRequest
ResolveRequest is the body of POST /api/v1/series/resolve.
type ResolveResponse ¶
type ResolveResponse struct {
// Results holds one result per request selector, in request order.
Results []ResolveResult `json:"results"`
}
ResolveResponse is the body of a successful resolve response: {"results":[…]}.
func (ResolveResponse) MarshalJSON ¶
func (r ResolveResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes {"results":[…]}; nil Results is written as [].
func (*ResolveResponse) UnmarshalJSON ¶
func (r *ResolveResponse) UnmarshalJSON(b []byte) error
UnmarshalJSON parses the response.
type ResolveResult ¶
type ResolveResult struct {
// Selector is the index of the request selector (0-based).
Selector int
// Select is the request selector, echoed.
Select Selector
// Assignments are the profile assignments of the selector; possibly empty, unset with an Error.
Assignments []Assignment
// Error is a selector-level error; exactly one of Assignments or Error is set.
Error *ResultError
}
ResolveResult is the outcome for one request selector of the resolve endpoint: either Assignments (possibly empty) or Error.
func (ResolveResult) MarshalJSON ¶
func (r ResolveResult) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the result.
func (*ResolveResult) UnmarshalJSON ¶
func (r *ResolveResult) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the result.
type ResultError ¶
type ResultError struct {
// Code is the record-level error code (snake_case); unknown codes are kept on read (see IsKnown)
// but refused on write.
Code RecordErrorCode `json:"code"`
}
ResultError is the error object of a resolve/versions result or assignment: {"code":"…"}.
func (ResultError) MarshalJSON ¶
func (r ResultError) MarshalJSON() ([]byte, error)
MarshalJSON validates before writing.
func (*ResultError) UnmarshalJSON ¶
func (r *ResultError) UnmarshalJSON(b []byte) error
UnmarshalJSON enforces the presence rules.
type Selector ¶
type Selector struct {
// By names the variant: "profile", "malo" or a snake_case customer resolver name of 1 to 30 characters.
By string
// Profile is the profile number (By "profile"): 1 to 18 digits; leading zeros are allowed in requests.
Profile string
// MaLo is the market location id (By "malo"): exactly 11 digits.
MaLo string
// Params are the string parameters of a customer resolver (any other By); keys are non-empty.
Params map[string]string
}
Selector names the business object whose profile assignments are queried. It is a union over By:
{"by":"profile","profile":"50000000000056"} – a profile number
{"by":"malo","malo":"87253749908"} – a market location
{"by":"<name>","params":{"<key>":"<string>"}} – a customer resolver
Build selectors with ProfileSelector, MaLoSelector or CustomSelector. Only the fields of the variant named by By are used; the others must be empty.
func CustomSelector ¶
CustomSelector selects via a customer resolver named by. params may be nil.
func MaLoSelector ¶
MaLoSelector selects the profiles assigned to a market location.
func ProfileSelector ¶
ProfileSelector selects a profile by number (leading zeros allowed).
func (Selector) MarshalJSON ¶
MarshalJSON writes the keys of the variant only, after validating with the request rules.
func (*Selector) UnmarshalJSON ¶
UnmarshalJSON accepts exactly the keys of the variant named by "by" (request rules).
type SeriesRecord ¶
type SeriesRecord struct {
// Series numbers the series of a response, starting at 1 and continuing across pages.
Series int
// Selector is the index of the request selector this series belongs to.
Selector int
// Select echoes the request selector (profile numbers without leading zeros).
Select Selector
// Profile is the SAP profile number, without leading zeros.
Profile string
// Role is the role of the profile assignment (SAP EPROFASS role, e.g. "0001"), or nil when the series
// was not resolved through a role (e.g. by: profile). The Resolver BAdI may override it.
Role *string
// From and To bound the assignment, cut to the request window.
From, To time.Time
// Unit is the canonical unit code (UN/ECE Rec. 20, e.g. "KWH") of the delivered values (after any
// conversion), or nil when the SAP unit has no mapping. The series is delivered either way.
Unit *string
// UnitRaw is the SAP unit key (T006 MSEHI) as SAP delivers it, mapped or not: any non-empty text of
// at most 30 characters without control characters.
UnitRaw string
// Interval is that of the delivered values (after any conversion).
Interval string
// Attributes come from the customer's Metadata BAdI; never nil after unmarshalling.
Attributes map[string]string
// Versions lists the profile versions overlapping the series; never nil after unmarshalling.
Versions []Version
}
SeriesRecord opens a series: one profile assignment of one selector, cut to the request window.
func (*SeriesRecord) MarshalJSON ¶
func (r *SeriesRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record with "type" first; a nil Role or Unit is written as null.
func (*SeriesRecord) RecordType ¶
func (*SeriesRecord) RecordType() string
RecordType returns "series".
func (*SeriesRecord) UnmarshalJSON ¶
func (r *SeriesRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type SystemInfo ¶
type SystemInfo struct {
// ServiceVersion is the version of the Zeitreiher service (Go).
ServiceVersion string
// AbapPackageVersion is the version of the ABAP package /HFQ/ZEITREIHER.
AbapPackageVersion string
// SID is the SAP system id.
SID string
// Client is the SAP client the service reads from.
Client string
// Release is the SAP release.
Release string
// BusinessTimeZone is the configured SAP time zone code, e.g. "CET".
BusinessTimeZone string
// Intervals lists the supported request intervals, e.g. ["PT15M","PT60M"].
Intervals []string
// Units lists the canonical unit codes (UN/ECE Rec. 20, e.g. "KWH") the system can map to SAP units;
// a request unit outside this list is a 400. Never nil after unmarshalling.
Units []string
// Caps are the per-call self-protection caps.
Caps Caps
// AbapLastSourceChangeUTC is the instant of the last source change of the ABAP package (whole seconds,
// written in UTC "Z"); nil when unknown, then the key is omitted. Absent and null both mean unknown.
AbapLastSourceChangeUTC *time.Time
// AbapInactiveObjects reports the inactive objects of the ABAP package; nil when the backend does not
// say, then the key is omitted.
AbapInactiveObjects *InactiveObjects
// AbapSourceFingerprint is the aggregate SHA-256 of the ABAP sources, exactly 64 lower-case hex
// characters; nil when unknown, then the key is omitted.
AbapSourceFingerprint *string
}
SystemInfo is the body of GET /api/v1/system (spec §4.4).
func (SystemInfo) MarshalJSON ¶
func (s SystemInfo) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the system info.
func (*SystemInfo) UnmarshalJSON ¶
func (s *SystemInfo) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the system info.
type ValueRecord ¶
type ValueRecord struct {
// Series is the number of the series record this value belongs to.
Series int
// From and To bound the value's interval.
From, To time.Time
// Value is the already-scaled decimal value.
Value Decimal
// Status holds the active SAP status codes overlapping the interval, sorted; never nil after
// unmarshalling.
Status []string
// Version is the source of the value: the number of the stored version row it came from, or nil
// when it is a current value. With {"number":N} a series mixes both: current values overlaid with
// the stored values of versions >= N (the lowest wins), only inside N's covered range.
Version *int
}
ValueRecord is one value of a series for the half-open interval [From, To).
func (*ValueRecord) MarshalJSON ¶
func (r *ValueRecord) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the record; a nil Version is written as null.
func (*ValueRecord) RecordType ¶
func (*ValueRecord) RecordType() string
RecordType returns "value".
func (*ValueRecord) UnmarshalJSON ¶
func (r *ValueRecord) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the record.
type Version ¶
type Version struct {
// Number is the SAP version number (CVERSNO), at least 1.
Number int
// From is the start of the covered range [From, To) (inclusive).
From time.Time
// To is the end of the covered range (exclusive); nil for an open end.
To *time.Time
// CreatedAt is the creation instant (UTC); nil when it cannot be determined.
CreatedAt *time.Time
// CreatedAtUnknown is true exactly when CreatedAt is nil.
CreatedAtUnknown bool
// Reason is SAP's VERSREASON; it may be empty.
Reason string
// Description is SAP's VERSDESCR; it may be empty.
Description string
// Deleted is true for versions flagged as deleted in SAP. They are still listed; querying their
// values gives an error record with code version_deleted.
Deleted bool
}
Version describes one EDM profile version that overlaps a series (spec §4.2, §5).
func (Version) MarshalJSON ¶
MarshalJSON validates and writes the version; To and CreatedAt are written as null when nil.
func (*Version) UnmarshalJSON ¶
UnmarshalJSON parses and validates the version.
type VersionSelector ¶
type VersionSelector struct {
// Current selects the current values; exclusive with Number.
Current bool
// Number is the version number to rebuild (at least 1); exclusive with Current.
Number *int
}
VersionSelector chooses which values a query returns (spec §5). Exactly one form is set:
{"current":{}} – the current values (the default when omitted)
{"number":3} – version 3 as SAP rebuilds it: the current values overlaid with the stored
values of versions >= 3 (the lowest version wins), only inside version 3's
covered range; outside it the series has gaps
v1 has no as-of selector; {"as_of":…} is rejected as an unknown key. Build it with CurrentVersion or VersionNumber.
func CurrentVersion ¶
func CurrentVersion() VersionSelector
CurrentVersion selects the current values.
func VersionNumber ¶
func VersionNumber(n int) VersionSelector
VersionNumber selects version n (see VersionSelector).
func (VersionSelector) MarshalJSON ¶
func (v VersionSelector) MarshalJSON() ([]byte, error)
MarshalJSON writes the single set form.
func (*VersionSelector) UnmarshalJSON ¶
func (v *VersionSelector) UnmarshalJSON(b []byte) error
UnmarshalJSON accepts exactly one of the two forms.
func (VersionSelector) Validate ¶
func (v VersionSelector) Validate() error
Validate checks that exactly one form is set and that it is valid.
type VersionedAssignment ¶
type VersionedAssignment struct {
Assignment
// Versions lists the versions overlapping the assignment; written as [] when empty, omitted with an Error.
Versions []Version
}
VersionedAssignment is one profile assignment of a versions result: an Assignment plus the overlapping versions. Versions is written as [] when there are none and omitted with an error.
func (VersionedAssignment) MarshalJSON ¶
func (v VersionedAssignment) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the assignment.
func (*VersionedAssignment) UnmarshalJSON ¶
func (v *VersionedAssignment) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the assignment; versions is required unless error is set.
type VersionsRequest ¶
type VersionsRequest = WindowRequest
VersionsRequest is the body of POST /api/v1/series/versions.
type VersionsResponse ¶
type VersionsResponse struct {
// Results holds one result per request selector, in request order.
Results []VersionsResult `json:"results"`
}
VersionsResponse is the body of a successful versions response: {"results":[…]}.
func (VersionsResponse) MarshalJSON ¶
func (r VersionsResponse) MarshalJSON() ([]byte, error)
MarshalJSON writes {"results":[…]}; nil Results is written as [].
func (*VersionsResponse) UnmarshalJSON ¶
func (r *VersionsResponse) UnmarshalJSON(b []byte) error
UnmarshalJSON parses the response.
type VersionsResult ¶
type VersionsResult struct {
// Selector is the index of the request selector (0-based).
Selector int
// Select is the request selector, echoed.
Select Selector
// Assignments are the profile assignments with their versions; possibly empty, unset with an Error.
Assignments []VersionedAssignment
// Error is a selector-level error; exactly one of Assignments or Error is set.
Error *ResultError
}
VersionsResult is the outcome for one request selector of the versions endpoint.
func (VersionsResult) MarshalJSON ¶
func (r VersionsResult) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the result.
func (*VersionsResult) UnmarshalJSON ¶
func (r *VersionsResult) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the result.
type WindowRequest ¶
type WindowRequest struct {
// Select lists one or more selectors; results come back per selector index.
Select []Selector
// From is the start of the request window (inclusive); RFC 3339, whole seconds, explicit offset.
From time.Time
// To is the end of the request window (exclusive, after From); RFC 3339, whole seconds, explicit offset.
To time.Time
}
WindowRequest is the body of the resolve and versions endpoints (spec §4.4): selectors and a window, nothing else.
func (WindowRequest) MarshalJSON ¶
func (w WindowRequest) MarshalJSON() ([]byte, error)
MarshalJSON validates and writes the request.
func (*WindowRequest) UnmarshalJSON ¶
func (w *WindowRequest) UnmarshalJSON(b []byte) error
UnmarshalJSON parses and validates the request; unknown keys (e.g. version, cursor) are rejected.
func (WindowRequest) Validate ¶
func (w WindowRequest) Validate() error
Validate checks the request.