trac.api¶
Module Contents¶
Classes¶
Request to read a batch of objects from the TRAC metadata store. |
|
Response to reading a batch of objects from the TRAC metadata store. |
|
Request to get an object from the TRAC metadata store. |
|
Request to read an object from the TRAC metadata store. |
|
Request for a search against the TRAC metadata store. |
|
Response to a search against the TRAC metadata store. |
|
Request to create or update an object in the TRAC metadata store. |
|
Public API reading, writing and searching for objects in the TRAC metadata store. |
- class trac.api.MetadataBatchRequest¶
Request to read a batch of objects from the TRAC metadata store.
See also
- selector :List[trac.metadata.TagSelector]¶
- tenant :str¶
- class trac.api.MetadataBatchResponse¶
Response to reading a batch of objects from the TRAC metadata store.
See also
- tag :List[trac.metadata.Tag]¶
- class trac.api.MetadataGetRequest¶
Request to get an object from the TRAC metadata store.
See also
- objectId :str¶
- objectType :trac.metadata.ObjectType¶
- objectVersion :Optional[int]¶
- tagVersion :Optional[int]¶
- tenant :str¶
- class trac.api.MetadataReadRequest¶
Request to read an object from the TRAC metadata store.
See also
- selector :trac.metadata.TagSelector¶
- tenant :str¶
- class trac.api.MetadataSearchRequest¶
Request for a search against the TRAC metadata store.
See also
- searchParams :trac.metadata.SearchParameters¶
- tenant :str¶
- class trac.api.MetadataSearchResponse¶
Response to a search against the TRAC metadata store.
See also
- searchResult :List[trac.metadata.Tag]¶
- class trac.api.MetadataWriteRequest¶
Request to create or update an object in the TRAC metadata store.
See also
- definition :Optional[trac.metadata.ObjectDefinition]¶
New object definition to save.
A definition is required to create or update an object, for tag updates the definition field should be left blank.
This field should be omitted for tag update operations.
- objectType :trac.metadata.ObjectType¶
Object type for the requested operation, always required.
- priorVersion :Optional[trac.metadata.TagSelector]¶
Prior object/tag version to use for update operations.
This field should be omitted when creating a new object.
- tagUpdates :List[trac.metadata.TagUpdate]¶
Tag update operations to be applied.
The updates are applied in order and must all succeeded in order for the request to be successful. If the API call fails for any reason, none of the requested tag updates will be applied.
- tenant :str¶
Tenant code for the requested operation, always required.
- class trac.api.TracMetadataApi¶
Public API reading, writing and searching for objects in the TRAC metadata store.
The TRAC metadata API is expressed in terms of Objects and Tags. Objects are structural items (nouns and verbs) such as data, models and jobs that describe resources and operations on the TRAC platform. Tags contain descriptive and informational data and provide a means to classify, catalogue and control objects. Tags can also be used to describe the structure of applications built on the TRAC platform. For more information on the TRAC metadata model, refer to the documentation for ObjectDefinition and Tag.
The write API allows objects to be created directly, by supplying an object definition and a set of tags. These definitions and tags are validated, assigned an ID and version (in a tag header) then saved as they are. Only certain types of objects can be created / updated directly via the public API (currently FLOW and CUSTOM objects). Other types of objects are created by TRAC as a result of operations on the platform, for example a model import job will create a model definition.
Creating a new version of an object is very similar to creating a new object, in that the entire metadata definition must be supplied. TRAC will perform validation to make sure the new definition is a valid version update from the previous version - the semantics of versioning depend on the particular object type.
The metadata write API also provides a means for updating tags (i.e. creating a new tag version); tag updates are allowed for all object types via the public API. The current API requires a whole new tag to be supplied, this will be replaced in a future version with an API that supplies attributes changes as a set of add/modify/remove operations.
The read API is for reading metadata from the metadata store when the IDs of the metadata items are known. The easiest way to read metadata is using TagSelectors, which may be present in other metadata items (e.g. job definitions record tag selectors to indicate which versions of resources were used in a job) or can be easily constructed from an object ID or tag header. HTTP GET calls are also available for REST clients (REST clients can still use selectors with POST requests).
Metadata searches are performed using tag attributes, as well as an object type and a few top-level parameters to handle versioning and temporality. See the SearchParameters object for a more detailed description. The result of a search call is a list of matching tags, which are always arranged with the most recent tags first. A search that matches no results will return an empty list.
This API is a multi-tenant API. For gRPC requests every request includes a tenant code, for REST requests the tenant code is the first element of every path.
See also
ObjectDefinition,Tag,TagHeader,TagSelector,TagUpdate,SearchParameters- createObject(self, request)¶
Create a new object in the TRAC metadata store.
To create an object, supply a metadata write request with the tenant code, object type and a definition for the item you want to save. The tag should contain all the attributes you want to set and the object definition, without an object header. TRAC will create a header when it assigns and ID for the new object. Only FLOW and CUSTOM objects can be created by this API call.
Validation is performed on new objects before they are saved. Objects can fail validation because they are semantically invalid (e.g. missing required fields or inconsistencies within the object definition) or due to consistency errors (referring to other metadata items that don’t exist or don’t meet certain requirements).
NOTE: Validation is only partially implemented in the current release.
The call returns an ID response to indicate the ID of the newly created object, as well as the object and tag version (which will always be 1).
Error conditions include: Invalid request, unknown tenant, object type does not match the supplied definition, validation failure.
See also
- Parameters
request (MetadataWriteRequest) –
- Return type
- getLatestObject(self, request)¶
Get the latest version of a metadata object using an HTTP GET request.
This call is intended for use by REST clients to provide TRAC metadata objects as RESTFUL resources. For gRPC clients it is recommended to use readObject instead and supply a TagSelector.
See also
To use this call, supply a tenant code, object type and ID. The call will return the latest version of the object with its latest tag, including the full object definition.
Error conditions include: Invalid request, unknown tenant, unknown object ID, object type does not match ID.
- Parameters
request (MetadataGetRequest) –
- Return type
- getLatestTag(self, request)¶
Get the latest tag for a metadata object using an HTTP GET request.
This call is intended for use by REST clients to provide TRAC metadata objects as RESTFUL resources. For gRPC clients it is recommended to use readObject instead and supply a TagSelector.
See also
To use this call, supply a tenant code, object type, ID and version. The call will return the latest tag for the specified version of the object, including the full object definition.
Error conditions include: Invalid request, unknown tenant, unknown object ID, object type does not match ID, unknown object version.
- Parameters
request (MetadataGetRequest) –
- Return type
- getObject(self, request)¶
Get a single metadata object using an HTTP GET request.
This call is intended for use by REST clients to provide TRAC metadata objects as RESTFUL resources. For gRPC clients it is recommended to use readObject instead and supply a TagSelector.
See also
To use this call, supply a tenant code, object type, ID, object version and tag version. The call will return a tag for the exact object version and tag version specified, including the full object definition.
Error conditions include: Invalid request, unknown tenant, unknown object ID, object type does not match ID, unknown object version, unknown tag version.
- Parameters
request (MetadataGetRequest) –
- Return type
- readBatch(self, request)¶
Read multiple objects from the TRAC metadata store using tag selectors.
Tag selectors are used throughout the TRAC metadata structures and API calls to refer to objects. For example, a job definition includes selectors to define the data sets and models that were selected for the job. Those selectors can be passed directly into this call.
Tag selectors can refer to object and tag versions either using explicit version numbers, with as-of times or by referring to the current latest version. Combinations are also possible (e.g. object version x, latest tag).
This call takes multiple selectors and returns multiple Tags in the same order, including their object definitions. Selectors for different object types and with different criteria for selecting versions can be mixed freely in a single request. Error conditions include: Invalid request, unknown tenant, unknown object ID, object type does not match ID, unknown object version, unknown tag version. If there is an error for any of the selectors the whole request will fail.
See also
- Parameters
request (MetadataBatchRequest) –
- Return type
- readObject(self, request)¶
Read a single object from the TRAC metadata store using a tag selector.
Tag selectors are used throughout the TRAC metadata structures and API calls to refer to objects. For example, a job definition includes selectors to define the data sets and models that were selected for the job. Those selectors can be passed directly into this call.
Tag selectors can refer to object and tag versions either using explicit version numbers, with as-of times or by referring to the current latest version. Combinations are also possible (e.g. object version x, latest tag).
This call takes a single selector and returns a single Tag, including the object definition. Error conditions include: Invalid request, unknown tenant, unknown object ID, object type does not match ID, unknown object version, unknown tag version.
See also
- Parameters
request (MetadataReadRequest) –
- Return type
- search(self, request)¶
Perform a search against the TRAC metadata store.
Searches are always for a specific tenant and object type. For details of the available search parameters, see SearchParameters.
In gRPC calls, a MetadataSearchRequest specifies the tenant and includes the SearchParameters, where object type and the search expression are set. For REST calls the tenant is passed in the URL and searchParameters are supplied as the request body.
See also
- Parameters
request (MetadataSearchRequest) –
- Return type
- updateObject(self, request)¶
Update an existing object in the TRAC metadata store.
To save a new version, supply a metadata write request with the tenant code, object type and a tag for the item you want to save. The tag should contain all the attributes you want to set and the updated object definition, which must be supplied with the header from the previous version of the object. TRAC will apply the new version number when it creates the new version of the object. Only the latest version of an object can be updated and only CUSTOM objects can be updated by this API call.
Validation is performed on new objects before they are saved. Objects can fail validation because they are semantically invalid (e.g. missing required fields or inconsistencies within the object definition) or due to consistency errors (referring to other metadata items that don’t exist or don’t meet certain requirements). For new versions, validation also covers checking for compatibility with the previous version of the object.
NOTE: Validation is only partially implemented in the current release.
The call returns an ID response with the ID object and the newly assigned version number, as well as the tag version (which will always be 1).
Error conditions include: Invalid request, unknown tenant, unknown object ID or version, wrong object type (not the same as the prior version), object version is superseded.
See also
- Parameters
request (MetadataWriteRequest) –
- Return type
- updateTag(self, request)¶
Update the tag for an existing object in the TRAC metadata store.
To save a new tag, supply a metadata write request with the tenant code, object type and a tag for the item you want to save. The tag should contain all the attributes you want to include in the new tag, even if they have not been changed. The object definition must be supplied with a header only, supplying an object body is an invalid request. Tags for any type of object can be updated by this API call. Only the latest version of a tag can be updated.
The call returns an ID response with the ID and version of the object and the newly assigned tag number.
Error conditions include: Invalid request, unknown tenant, unknown object ID, object version or tag version, wrong object type (does not match what is stored in TRAC), tag version is superseded.
See also
- Parameters
request (MetadataWriteRequest) –
- Return type