@itwin/core-backend/lib/cjs/BlobContainerService.d.ts

iTwin.js backend components

/** @packageDocumentation
 * @module BlobContainers
 */
import { AccessToken, GuidString, Id64String } from "@itwin/core-bentley";
import { SettingsContainer } from "./workspace/Settings";
/**
 * Types and functions for creating, deleting and authorizing access to cloud-based blob containers for an iTwin.
 * @beta
 */
export declare namespace BlobContainer {
    /** Object that implements the methods to create, delete, and request access to a container. */
    let service: BlobContainer.ContainerService | undefined;
    /** name of cloud provider for a container. */
    type Provider = "azure" | "google";
    /** the name of the container within its `Scope` */
    type ContainerId = string;
    /** token that authenticates a user. This token is required to obtain a `ContainerToken`. */
    type UserToken = AccessToken;
    /** token that authenticates access to a container for either read or write. */
    type ContainerToken = AccessToken;
    /**
     * The scope for a container. This determines:
     *  - the "owner" organization, including the contract that governs its legal and commercial terms and obligations
     *  - the administrators who may configure RBAC permissions
     *  - the datacenter for the container. Every container resides in a datacenter as determined by the iTwinId. This
     * determines the region for data residency requirements.
     *  - the lifecycle constraints for the container. No container can outlive its iTwin or its iModel (if defined). That is,
     * when the iTwin/iModel is deleted (either explicitly or due to contract expiration), the container is also deleted.
     */
    interface Scope {
        /** iTwinId of the owner of this container. */
        iTwinId: Id64String;
        /** optionally, an iModelId within the iTwin. If present, container is deleted when the iModel is deleted. */
        iModelId?: Id64String;
        /** the user GUID an individual, if this container is private. */
        ownerGuid?: GuidString;
    }
    /**
     * Metadata about the use of a container so that:
     *  - administrators can understand why a container exists for assigning RBAC permissions appropriately
     *  - usage reports can aggregate types of containers
     *  - applications can identify their containers
     *  - applications can store properties about their containers
     */
    interface Metadata {
        /** The machine-readable string that describes what the container is being used for (e.g. "workspace"). Always lowercase and singular. */
        containerType: string;
        /** Human-readable name for the container. This will be displayed in the administrator RBAC panel, and on usage reports. Not required to be unique.*/
        label: string;
        /** Optional human-readable explanation of the information held in the container. This will be displayed in the administrator RBAC panel, and on usage reports. */
        description?: string;
        /** optional properties for the container */
        json?: SettingsContainer;
    }
    /**
     * Properties returned by queryContainersMetadata
     */
    interface MetadataResponse extends Metadata {
        containerId: string;
    }
    /** Properties returned by `Service.requestToken` */
    interface TokenProps {
        /**
         * Expiring token that provides the requested access to the container. Should be used in all subsequent requests for blobs within the container,
         * and must be refreshed before it expires
         */
        token: ContainerToken;
        /** Scope of the container. */
        scope: Scope;
        /** Name of the blob storage provider. */
        provider: Provider;
        /** Time at which the token will expire. The token should be refreshed (that is, a new token should be requested) before this time. */
        expiration: Date;
        /** Metadata of the container. */
        metadata: Metadata;
        /** Base URI of the storage account that hosts the container */
        baseUri: string;
    }
    /** The URI and Id of the container. */
    interface UriAndId {
        baseUri: string;
        containerId: ContainerId;
    }
    /** Information required to access an existing container. */
    interface AccessContainerProps extends UriAndId {
        userToken: UserToken;
    }
    /** Information about a newly created container. */
    interface CreatedContainerProps extends UriAndId {
        /** name of the blob storage provider. */
        provider: Provider;
    }
    /**
     * Access level to request for token.
     * - `"write"`: request a writeable AccessToken.
     * - `"read"`:  request a read-only AccessToken.
     * - `"admin"`:  request a admin AccessToken.
     * - `"writeIfPossible"`: first request a writeable AccessToken. If the user is not authorized for write, request a read-only AccessToken.
     * If the user is not authorized for the level requested, an exception is thrown.
     */
    type RequestAccessLevel = "write" | "read" | "admin" | "writeIfPossible";
    /** Information required to request an access token for a container. */
    interface RequestTokenProps extends Omit<AccessContainerProps, "baseUri"> {
        /** the level of access requested. If not specified, defaults to `"writeIfPossible"`. */
        accessLevel?: RequestAccessLevel;
        /** the number of seconds before the token should expire.
         * @note A maximum duration is determined by the service. If no value is supplied, or the value is larger than the maximum, the maximum duration is used.
         */
        durationSeconds?: number;
    }
    /** Information required to create a new container. */
    interface CreateNewContainerProps {
        /** the scope of the new container */
        scope: Scope;
        /** metadata to be stored on the new container */
        metadata: Metadata;
        /** The user's access token. The user must be authorized with "create container" RBAC role for the iTwin. */
        userToken: UserToken;
        /**
         * the id for the container. Useful for tests.
         * @internal
         */
        containerId?: ContainerId;
    }
    /**
     * Query Parameters for querying containers
     */
    interface QueryContainerProps {
        /** the iTwinId of the containers to query */
        iTwinId: GuidString;
        /** optional iModelId of the containers to query */
        iModelId?: GuidString;
        /** optional containerType of the containers to query */
        containerType?: GuidString;
        /** optional label of the containers to query */
        label?: GuidString;
    }
    /** Methods to create, delete, and access blob containers. */
    interface ContainerService {
        /**  Create a new blob container. Throws on failure (e.g. access denied or container already exists.) */
        create(props: CreateNewContainerProps): Promise<CreatedContainerProps>;
        /**
         * Delete an existing blob container.
         * @note This method requires that the user be authorized with "delete container" RBAC role for the iTwin.
         */
        delete(container: AccessContainerProps): Promise<void>;
        /** query the Scope for a container */
        queryScope(container: AccessContainerProps): Promise<Scope>;
        /** query the Metadata for a specific container */
        queryMetadata(container: AccessContainerProps): Promise<Metadata>;
        /** Returns all containers and their metadata associated with a given iTwinId. Can be further queried by label and containerType. */
        queryContainersMetadata(userToken: UserToken, args: QueryContainerProps): Promise<MetadataResponse[]>;
        /** update the json properties of this container */
        updateJson(container: AccessContainerProps, json: SettingsContainer): Promise<void>;
        /** Request a `ContainerToken` for a container. Throws on failure. */
        requestToken(props: RequestTokenProps): Promise<TokenProps>;
    }
}
//# sourceMappingURL=BlobContainerService.d.ts.map