IPackageApi

title: “IPackageApi” description: “IPackageApi Interface” lead: "" date: 2023-06-12T13:46:25-06:00 lastmod: 2023-06-12T13:46:25-06:00 draft: false images: [] menu: docs: parent: “dotnet-api” weight: 323 toc: true

Interface Reference

Definition

Provides an interface to call the Package Registration API.

Namespace: TrimbleCloud.Tam
Assembly: TrimbleCloud.Tam.dll

public interface IPackageApi

Initialization

This interface will be injected through AddAccessManagement.

Methods

Register

Registers a policy package with Trimble Access Management.

Task<JobReason> Register(string packageNamespace, string fileTrn, string testFileTrn, List<RemoteDataSource> remoteDataSources, string? contactName, string? contactEmail, string? description, string? example, List<string>? packageDependencyNamespaces, CancellationToken cancellation);

Parameters

packageNamespace string The namespace of the package to register.

filePath string A path on the local file system to a rego file or directory of rego files.

testFilePath string A path on the local file system to a rego test file or directory of rego test files.

remoteDataSources List<RemoteDataSource> A list of remote data sources associated with the policy.

contactName string (Optional) A contact name to associate with the package being registered.

contactEmail string (Optional) A contact email to associate with the package being registered.

description string (Optional) A description of the package being registered.

example string (Optional) An example of the package being registered.

isDiscoverable bool (Optional) Boolean to set if registered package is publicly discoverable. When registered with true, registered package is publicly discoverable and is not public when registered with false.

packageDependencyNamespaces List<string> (Optional) A list of package namespaces corresponding to dependencies of the package being registered.

cancellation CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

An object containing the revision number of the registered package (Revision).

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Remarks

This operation will not block. The returned Task object will complete after the registration is complete.

ContactName, ContactEmail, PackageDescription, and PackageExample are not required to register a package and null or string.Empty can be entered in their place.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

var response = await packageApi.Register("trimble.example.package", "c:\\file.rego", "c:\\file_test.rego", new List<RemoteDataSource> { new RemoteDataSources { remoteDataSourceUrl = "https://api.foo.trimble.com", expiration = TimeSpan.FromMinutes(1), scope = "foo" } }, "Package Owner", "package.owner@trimble.com", "This is a description of the example package", "This is an example of the example package", CancellationToken.None);
var revision = response.Revision

GetLatestPackage

Gets a package’s latest revision and creation date from Trimble Access Management based on a given package namespace. If package metadata exists, it is also retrieved.

Task<PackageGetResponse> GetLatestPackage(string packageNamespace, CancellationToken cancellationToken);

Parameters

packageNamespace string The namespace of the package from which to retrieve information. Case-sensitive.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

An object containing the requested package’s latest approved revision (PackageRevision), the date the requested package was created (PackageCreationDate), and any registered package metadata (ContactName, ContactEmail, PackageDescription, and PackageExample).

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Remarks

Will return an object with null values for PackageRevision and PackageCreationDate if requested package has never been registered, has not passed package validation, or is not set as publicly discoverable. ContactName, ContactEmail, PackageDescription, and PackageExample are not required during registration and can be null if these values were never registered on an otherwise healthy package.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.GetLatestPackage("trimble.example.package", CancellationToken.None);

GetPackageByRevision

Gets a specific package’s information from Trimble Access Management based on a given package namespace and specific package revision. If package metadata exists, it is also retrieved.

Task<PackageGetResponse> GetPackageByRevision(string packageNamespace, int revision, CancellationToken cancellationToken);

Parameters

packageNamespace string The namespace of the package from which to retrieve information. Case-sensitive.

revision int The specific revision of the package from which to retrieve information.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Remarks

Will return an object with null values for PackageRevision and PackageCreationDate if specific requested package has never been registered, has not passed package validation, or is not set as publicly discoverable. ContactName, ContactEmail, PackageDescription, and PackageExample are not required during registration and can be null if these values were never registered on an otherwise healthy package.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.GetPackageByRevision("trimble.example.package", 3, CancellationToken.None);

GetAllPackages

Gets the namespaces and revisions of all your approved packages in a paginated return format. If search criteria is specified, only package namespaces containing the search criteria will be included. Package filtering can be achieved with the help of ‘isDiscoverable’ argument.

Task<GetAllPackagesResponse> GetAllPackages(string? searchCriteria, int? pageIndex, int? pageSize, bool? isDiscoverable, CancellationToken cancellationToken);

Parameters

searchCriteria string The searchCriteria to narrow resulting package namespaces. If specified, results will include only packages with namespaces containing the specified search criteria. If null, all discoverable and approved packages will be returned. Case-insensitive.

pageIndex int The page index specifying which page of the paginated results to return. Default is 0.

pageSize int The page size specifying how many resulting items are included in each page of the paginated results. Default is 100.

isDiscoverable bool The isDiscoverable accepts a boolean value. It is used to filter packages based on discoverable & non-discoverable criteria. If not specified, both discoverable & non-discoverable packages will be returned. If set to ‘true’, only discoverable packages will be returned. If set to ‘false’, only non-discoverable packages will be returned.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

An object containing the total number of results for the operation, the current page index of the paginated results (matches pageIndex input), the resulting items for the given page, and a set of links to navigate the paginated results. The resulting items is a list of namespaces and revisions of approved and discoverable packages for the given page index and size inputs. The links to navigate paginated responses contain links to the current page (self), the next page (next), the previous page (prev), the first page (first), and the last page (last) (see Trimble API Standards for Pagination).

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Remarks

Will always return an object response even if no results match the request. If no packages match the request the object will return with TotalItems = 0. If a package has multiple revisions where some revisions are unapproved or not discoverable, only the revisions that are approved and discoverable will be returned via this method.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.GetAllPackages("optionalSearchCriteria", 1, 50, false, CancellationToken.None);

GetPublicPackages

Gets the namespaces and revisions of all approved and discoverable packages(publicly) in a paginated return format. If search criteria is specified, only package namespaces containing the search criteria will be included.

Task<GetAllPackagesResponse> GetPublicPackages(string? searchCriteria, int? pageIndex, int? pageSize, CancellationToken cancellationToken);

Parameters

pageIndex int The page index specifying which page of the paginated results to return. Default is 0.

pageSize int The page size specifying how many resulting items are included in each page of the paginated results. Default is 100.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Remarks

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.GetPublicPackages("optionalSearchCriteria", 1, 50, CancellationToken.None);

Update

Update the Metadata of a specific version of a package.

Task<PackageGetResponse> UpdatePackageMetadata(string packageNamespace, int packageRevision, string contactName, string contactEmail, string description, string example, bool? isDiscoverable, CancellationToken cancellation);

Parameters

packageNamespace string The namespace of the package from which to retrieve information. Case-sensitive.

revision int The specific revision of the package from which to retrieve information.

contactName string (Optional) A contact name to associate with the package being registered.

contactEmail string (Optional) A contact email to associate with the package being registered.

description string (Optional) A description of the package being registered.

example string (Optional) An example of the package being registered.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

An object containing the updated package’s revision (PackageRevision), the date the requested package was created (PackageCreationDate), and any registered package metadata (ContactName, ContactEmail, PackageDescription, and PackageExample).

Exceptions

AccessManagementException The decision wasn’t able to be evaluated due to failure status code returned from the Server API.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.UpdatePackageMetadata("trimble.example.package", 3,"Package Owner", "package.owner@trimble.com", "This is a description of the example package", "This is an example of the example package", true, CancellationToken.None);

DeletePackage

Deletes all revisions of a package from Trimble Access Management that matches the provided namespace.

Task<string> DeletePackage(string packageNamespace, CancellationToken cancellation);

Parameters

packageNamespace string The namespace of the package to delete.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

The response content as a string representing the number of packages deleted from the service after successfully deleting all revisions of the specified package.

Exceptions

AccessManagementException Thrown when the package deletion fails.

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.DeletePackage("trimble.example.package", CancellationToken.None);

DeletePackageByRevision

Deletes a specific revision of a package from Trimble Access Management.

Task<string> DeletePackageByRevision(string packageNamespace, int packageRevision, CancellationToken cancellation);

Parameters

packageNamespace string The namespace of the package to delete.

revision int packageRevision int The specific revision of the package to delete. Must be greater than zero.

cancellationToken CancellationToken A cancellation token that can be used by other objects or threads to receive notice of cancellation.

Returns

Task

The response content as a string represent the number of packages deleted from the service after successfully deleting the specified package revision.

Exceptions

AccessManagementException Thrown when the package deletion fails, or if the specified package revision is invalid (less than zero).

Example

var sc = new ServiceCollection();
serviceCollection.AddAccessManagement(environment, consumerKey, consumerSecret, applianceUrl);
var serviceProvider = serviceCollection.BuildServiceProvider();
var packageApi = serviceProvider.GetRequiredService<IPackageApi>();

await packageApi.DeletePackageByRevision("trimble.example.package", 3, CancellationToken.None);