diff --git a/site/docs/services/omas/asset-catalog/get-asset-classifications.md b/site/docs/services/omas/asset-catalog/get-asset-classifications.md new file mode 100644 index 0000000000..916e3b6f78 --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-asset-classifications.md @@ -0,0 +1,36 @@ + + + +# Get Asset Classifications + +This is the ability to retrieve all classifications that exist on a specific asset. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [ClassificationListResponse getClassificationsForAsset(String userId, String assetGUID, String assetType, String classificationName) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getClassificationsForAsset(java.lang.String,java.lang.String,java.lang.String,java.lang.String)) + +## REST endpoint +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/supportedTypes +``` +Path and request parameters: +* `serverName` - unique identifier for requested server +* `userId` - the unique identifier for the user +* `assetGUID` - the unique identifier for the asset +* `assetType` - the type of the asset +* `classificationName` - the name of the classification + +Response: +* `ClassificationsResponse` - the classification for the asset + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/get-asset-context.md b/site/docs/services/omas/asset-catalog/get-asset-context.md new file mode 100644 index 0000000000..bd4eb1a67a --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-asset-context.md @@ -0,0 +1,37 @@ + + + +# Get Asset Context + +Return the full context of an asset/glossary term based on its identifier. +The response contains the list of the connections assigned to the asset. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [AssetResponse getAssetContext(String userId, String assetGUID, String assetType) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getAssetContext(java.lang.String,java.lang.String,java.lang.String)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-context/{{asset-guid}} +``` +Path and request parameters: +* `serverName` - unique identifier for requested server. +* `userId` - the unique identifier for the user +* `assetGUID` - the global unique identifier of the asset +* `assetType` - the type of the asset + +Response: +* `AssetResponse` - list of properties used to narrow the search + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/get-asset-details.md b/site/docs/services/omas/asset-catalog/get-asset-details.md new file mode 100644 index 0000000000..04acda61c9 --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-asset-details.md @@ -0,0 +1,36 @@ + + + +# Get Asset Details + +Fetches asset's properties, relationships and classifications. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [AssetCatalogResponse getAssetDetails(String userId, String assetGUID, String assetType) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getAssetDetails(java.lang.String,java.lang.String,java.lang.String)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-details/{{asset-guid}} +``` +Path and request parameters: +* `serverName` - unique identifier for requested server. +* `userId` - the unique identifier for the user +* `assetGUID` - the global unique identifier of the asset +* `assetType` - the type of the asset + +Response: +* `AssetCatalogResponse` - list of properties used to narrow the search + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/get-asset-relationships.md b/site/docs/services/omas/asset-catalog/get-asset-relationships.md new file mode 100644 index 0000000000..946e9c82fa --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-asset-relationships.md @@ -0,0 +1,39 @@ + + + +# Get Asset Relationships + +Fetches the relationships for a specific asset. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [RelationshipResponse getRelationshipBetweenEntities(String userId, String entity1GUID, String entity2GUID, String relationshipType) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getRelationshipBetweenEntities(java.lang.String,java.lang.String,java.lang.String,java.lang.String)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-relationships/{{asset-guid}}?assetType={{asset-type}}&relationshipType={{relationship-type}} +``` +Path and request parameters: +* `serverName` - unique identifier for requested server +* `userId` - the unique identifier for the user +* `assetGUID` - the unique identifier for the asset +* `assetType` - the type of the asset +* `relationshipType` - the type of the relationship +* `from` - offset +* `pageSize` - limit the number of the assets returned + +Response: +* `RelationshipListResponse` - list of relationships for the given asset + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/get-asset-universe.md b/site/docs/services/omas/asset-catalog/get-asset-universe.md new file mode 100644 index 0000000000..2c3e9078d3 --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-asset-universe.md @@ -0,0 +1,36 @@ + + + +# Get Asset Universe + +Fetches asset's header, classification, properties and relationships. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [AssetCatalogResponse getAssetUniverse(String userId, String assetGUID, String assetType) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getAssetUniverse(java.lang.String,java.lang.String,java.lang.String)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-relationships/{{asset-guid}}?assetType={{asset-type}}&relationshipType={{relationship-type}} +``` +Path and request parameters: +* `serverName` - unique identifier for requested server +* `userId` - the unique identifier for the user +* `assetGUID` - the unique identifier for the asset +* `assetType` - the type of the asset + +Response: +* `AssetCatalogResponse` - the asset with its header and the list of associated classifications and relationship + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/get-supported-types.md b/site/docs/services/omas/asset-catalog/get-supported-types.md new file mode 100644 index 0000000000..8598e4f23a --- /dev/null +++ b/site/docs/services/omas/asset-catalog/get-supported-types.md @@ -0,0 +1,35 @@ + + + +# Get Supported Types + +Returns the list with supported types for search, including the sub-types supported. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [AssetCatalogSupportedTypes getSupportedTypes(String userId, String type) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#getSupportedTypes(java.lang.String,java.lang.String)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/supportedTypes +``` +Path and request parameters: +* `serverName` - unique identifier for requested server +* `userId` - the unique identifier for the user +* `type` - the type + +Response: +* `AssetCatalogSupportedTypes` - list of types and sub-types supported for search + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + + diff --git a/site/docs/services/omas/asset-catalog/overview.md b/site/docs/services/omas/asset-catalog/overview.md index 88568903cf..6857e99c31 100644 --- a/site/docs/services/omas/asset-catalog/overview.md +++ b/site/docs/services/omas/asset-catalog/overview.md @@ -1,7 +1,7 @@ ---8<-- "snippets/content-status/in-development.md" +--8<-- "snippets/content-status/tech-preview.md" # Asset Catalog Open Metadata Access Service (OMAS) @@ -21,47 +21,52 @@ to it. This includes: * assets The Asset Catalog REST API supports: - * the retrieval of assets based on unique identifiers * the retrieval of asset's relationships and classifications -* the retrieval of assets based on known classification or relationship -* to query for related assets and to retrieve an asset neighborhood +* to query for related assets +* the retrieval of assets based on their type The module structure for the Asset Catalog OMAS is as follows: - * [asset-catalog-client](asset-catalog-client) supports the client library. * [asset-catalog-api](asset-catalog-api) supports the common Java classes that are used both by the client and the server. * [asset-catalog-server](asset-catalog-server) supports the server side implementation of the access service. - This includes the - * interaction with the [administration services](/services/admin-services/overview) for - registration, configuration, initialization and termination of the access service. - * interaction with the [repository services](/services/omrs) to work with open metadata from the - [cohort](/concepts/cohort-member). - * support for the access service's API and its related event management. -* [asset-catalog-spring](asset-catalog-spring) supports the REST API using the [Spring](/guides/contributor/runtime/#spring) libraries. + This includes the + * interaction with the [administration services](../../admin-services) for + registration, configuration, initialization and termination of the access service. + * interaction with the [repository services](../../repository-services) to work with open metadata from the + [cohort](https://egeria-project.org/concepts/cohort-member). + * support for the access service's API and its related event management. +* [asset-catalog-spring](asset-catalog-spring) supports the REST API using the [Spring](../../../developer-resources/Spring.md) libraries. +* [asset-catalog-topic-connector](asset-catalog-topic-connector) supports asynchronous messaging through a connector + and connector provider class + +## Using the Asset Catalog OMAS + +Below is the list of tasks supported by Asset Catalog OMAS. + +#### [Get Asset Classifications](get-asset-classifications.md) +#### [Get Asset Context](get-asset-context.md) +#### [Get Asset Details](get-asset-details.md) +#### [Get Asset Relationships](get-asset-relationships.md) +#### [Get Asset Universe](get-asset-universe.md) +#### [Get Supported Types](get-supported-types.md) +#### [Search](search.md) + -###Search solution +## Search Solution The search will return Assets, Glossary Terms and Schema Elements that match the search criteria. -As the asset search is to be performed against on one or more repositories a search engine will be used. +As the asset search is to be performed against on one or more repositories a search engine will be used. The search will be performed using the existing properties of the asset, glossary terms and/or schema elements. Indexing will be performed by the Asset Catalog OMAS according to supported zones. The search result will contain: guid, name (name or displayName), description, qualifiedName, classifications, zoneMembership (the basic properties of the element). In order to get the full context of the element, a second call is performed. At this step, the specific relationships are traverse for getting the connection to the asset and to get the schema type that is behind the given asset. -This call is using the asset global identifier and the asset type. +This call is using the asset global identifier and the asset type. ![Figure 1: Search](egeria-asset-search.png) -> Figure 1:Integration of search engine - -###Other Services -Asset Catalog OMAS provides services to fetch the asset -* classifications -* relationships -* specific entities that connects two assets -* relationships between two known entities -* related assets +> Figure 1: Integration of search engine --8<-- "snippets/abbr.md" diff --git a/site/docs/services/omas/asset-catalog/samples/collections/Asset-Catalog-endpoints.postman_collection.json b/site/docs/services/omas/asset-catalog/samples/collections/Asset-Catalog-endpoints.postman_collection.json new file mode 100644 index 0000000000..8d5e458bdd --- /dev/null +++ b/site/docs/services/omas/asset-catalog/samples/collections/Asset-Catalog-endpoints.postman_collection.json @@ -0,0 +1,290 @@ +{ + "info": { + "_postman_id": "bc085e19-5492-4446-b323-6ce7c7a0642f", + "name": "Asset Catalog endpoints", + "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" + }, + "item": [ + { + "name": "1. Get supported types", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/supportedTypes?type={{asset-type}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "supportedTypes" + ], + "query": [ + { + "key": "type", + "value": "{{asset-type}}" + } + ] + } + }, + "response": [] + }, + { + "name": "2. Search", + "request": { + "method": "POST", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "value": "application/json", + "type": "text" + } + ], + "body": { + "mode": "raw", + "raw": "{\n\t\"class\": \"SearchParameters\",\n\t\"status\": \"ACTIVE\",\n\t\"from\": 0,\n\t\"pageSize\":100,\n\t\"isCaseInsensitive\": false\n}", + "options": { + "raw": { + "language": "json" + } + } + }, + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/search?searchCriteria={{search-criteria}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "search" + ], + "query": [ + { + "key": "searchCriteria", + "value": "{{search-criteria}}" + } + ] + } + }, + "response": [] + }, + { + "name": "3. Get asset details", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-details/{{asset-guid}}/?assetType={{asset-type}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "asset-details", + "{{asset-guid}}", + "" + ], + "query": [ + { + "key": "assetType", + "value": "{{asset-type}}" + } + ] + } + }, + "response": [] + }, + { + "name": "4. Get asset classifications", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-classifications/{{asset-guid}}?classificationName={{classification-name}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "asset-classifications", + "{{asset-guid}}" + ], + "query": [ + { + "key": "from", + "value": "0", + "disabled": true + }, + { + "key": "pageSize", + "value": "10", + "disabled": true + }, + { + "key": "assetType", + "value": "{{asset-type-1}}", + "disabled": true + }, + { + "key": "classificationName", + "value": "{{classification-name}}" + } + ] + } + }, + "response": [] + }, + { + "name": "5. Get asset relationships", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-relationships/{{asset-guid}}?assetType={{asset-type}}&relationshipType={{relationship-type}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "asset-relationships", + "{{asset-guid}}" + ], + "query": [ + { + "key": "assetType", + "value": "{{asset-type}}" + }, + { + "key": "relationshipType", + "value": "{{relationship-type}}" + } + ] + } + }, + "response": [] + }, + { + "name": "6. Get asset context", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-context/{{asset-guid}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "asset-context", + "{{asset-guid}}" + ] + } + }, + "response": [] + }, + { + "name": "7. Get asset universe", + "request": { + "method": "GET", + "header": [ + { + "key": "Content-Type", + "name": "Content-Type", + "type": "text", + "value": "application/json" + } + ], + "url": { + "raw": "{{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/asset-universe/{{asset-guid}}", + "host": [ + "{{base-url}}" + ], + "path": [ + "servers", + "{{server-id}}", + "open-metadata", + "access-services", + "asset-catalog", + "users", + "{{user-id}}", + "asset-universe", + "{{asset-guid}}" + ] + } + }, + "response": [] + } + ] +} \ No newline at end of file diff --git a/site/docs/services/omas/asset-catalog/search.md b/site/docs/services/omas/asset-catalog/search.md new file mode 100644 index 0000000000..e5e124ba24 --- /dev/null +++ b/site/docs/services/omas/asset-catalog/search.md @@ -0,0 +1,36 @@ + + + +# Search + +Returns the list with supported types for search, including the sub-types supported. + +## Java client + +AssetCatalog.java, method (more details in javadoc): [AssetListResponse searchByType(String userId, String searchCriteria, SearchParameters searchParameters) throws InvalidParameterException, PropertyServerException;](https://odpi.github.io/egeria/org/odpi/openmetadata/accessservices/assetcatalog/AssetCatalog.html#searchByType(java.lang.String,java.lang.String,org.odpi.openmetadata.accessservices.assetcatalog.model.rest.body.SearchParameters)) + +## REST endpoint + +``` +GET {{base-url}}/servers/{{server-id}}/open-metadata/access-services/asset-catalog/users/{{user-id}}/supportedTypes +``` +Path and request parameters: +* `serverName` - unique identifier for requested server +* `userId` - the unique identifier for the user +* `searchCriteria` - a string expression of the characteristics of the required assets +* `searchParameters` - constrains to make the assets' search results more precise + +Response: +* `AssetListResponse` - list of found assets + +More examples can be found in the +[sample collection](samples/collections/Asset-Catalog-endpoints.postman_collection.json). + +---8<-- "snippets/abbr.md" + + + + + + +