From 8c4c6fae70274d71eb4744fdcddea31113a23aa9 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20D=C3=BCmont?= Date: Tue, 27 Aug 2024 11:06:53 +0200 Subject: [PATCH 1/3] Initial --- README.md | 80 ++++++++++++++++++++++++++++++++++++++++++++++++++----- 1 file changed, 74 insertions(+), 6 deletions(-) diff --git a/README.md b/README.md index 9197c791a..f06efdbcd 100644 --- a/README.md +++ b/README.md @@ -412,14 +412,56 @@ DeploymentApi api = new DeploymentApi(client); For more customization, creating a [HeaderProvider](https://sap.github.io/cloud-sdk/docs/java/features/connectivity/http-destinations#about-headerproviders) is also possible. -## Requirements and Setup +## Requirements and Setup for AI Core -### Set AI Core credentials as environment variable +For any AI Core service interaction, the SAP Cloud SDK for AI requires credentials to be available. +By default, the credentials are extracted automatically from a service instance of type "aicore" bound to the application. +Running the application locally without such a service binding will throw an exception: -- Running the application locally without a service binding will throw: +``` +Could not find any matching service bindings for service identifier 'aicore' +``` + +There are multiple options to register the service binding: +* Regular service binding in SAP BTP Cloud Foundry (resulting in `VCAP_SERVICES` env var entry). +* Set an environment variable explicitly: `AICORE_SERVICE_KEY` +* Define and use a _Destination_ in _BTP Destination Service_. +* Leveraging `"user-provided"` service binding (currently not recommended). +* Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` declaration in application (not recommended). + +### Regular service binding in SAP BTP Cloud Foundry + +* In the _SAP BTP Cockpit_ navigate to the target application. + Go to _Service Bindings_ and click _Bind Service_. + In the wizard create or bind an existing service instance of type `aicore`. +* (Or) use `manifest.yaml` to add the service binding declaratively. +* (Or) use CF CLI to add service binding on command line. + +
After application restart, there should be an "aicore" entry in environment variable VCAP_SERVICES. + +```json +{ + "aicore": [ + { + "clientid": "...", + "clientsecret": "...", + "url": "...", + "identityzone": "...", + "identityzoneid": "...", + "appname": "...", + "serviceurls": { + "AI_API_URL": "..." + } + } + ] +} +``` + +
- `Could not find any matching service bindings for service identifier 'aicore'` -- Go into the BTP Cockpit +### Set credentials as dedicated environment variable + +- Go into the SAP BTP Cockpit - Instances and Subscriptions -> Instances -> AI Core -> View Credentials -> Copy JSON - Set it as an environment variable `AICORE_SERVICE_KEY` in your IDE @@ -428,7 +470,33 @@ For more customization, creating a [HeaderProvider](https://sap.github.io/cloud- export AICORE_SERVICE_KEY='{ "serviceurls": { "AI_API_URL": ...' ``` -### Run the Spring Boot application +### Define and use a Destination + +* Lookup service-key credentials as explained in the previous step for `AICORE_SERVICE_KEY`. + +
Define a new destination in the _SAP BTP Destination Service_ using the service-key credentials. + + * (Destinations can be added on subaccount level and on service instance level.) + * (The URL field requires an additional path segment: `/v2`) + * Name: _my-aicore_ + * Type: HTTP + * URL: _[serviceurls.AI_API_URL]/v2_ + * Proxy-Type: Internet + * Authentication: _Oauth2ClientCredentials_ + * Client ID: _[clientid]_ + * Client Secret: _[clientsecret]_ + * Token Service URL Type: Dedicated + * Token Service URL: _[url]_ + +
+ +* In the application at runtime the following can be executed: + ```java + Destination destination = DestinationAccessor.getDestination("my-aicore"); + ApiClient client = Core.getClient(destination); + ``` + +### Run the Spring Boot test application ```shell cd e2e-test-app From ff57caa0452dd65e19baa508244fd869205dbfa6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20D=C3=BCmont?= <22489773+newtork@users.noreply.github.com> Date: Tue, 27 Aug 2024 11:13:45 +0200 Subject: [PATCH 2/3] Minor --- README.md | 36 ++++++++++++++++++------------------ 1 file changed, 18 insertions(+), 18 deletions(-) diff --git a/README.md b/README.md index f06efdbcd..c3988075f 100644 --- a/README.md +++ b/README.md @@ -414,9 +414,9 @@ For more customization, creating a [HeaderProvider](https://sap.github.io/cloud- ## Requirements and Setup for AI Core -For any AI Core service interaction, the SAP Cloud SDK for AI requires credentials to be available. +For any AI Core service interaction, the SAP Cloud SDK for AI requires credentials to be available at application runtime. By default, the credentials are extracted automatically from a service instance of type "aicore" bound to the application. -Running the application locally without such a service binding will throw an exception: +Running the application locally without such service binding will throw an exception: ``` Could not find any matching service bindings for service identifier 'aicore' @@ -435,7 +435,7 @@ There are multiple options to register the service binding: Go to _Service Bindings_ and click _Bind Service_. In the wizard create or bind an existing service instance of type `aicore`. * (Or) use `manifest.yaml` to add the service binding declaratively. -* (Or) use CF CLI to add service binding on command line. +* (Or) use the CF CLI to add the service binding via command line.
After application restart, there should be an "aicore" entry in environment variable VCAP_SERVICES. @@ -474,23 +474,23 @@ export AICORE_SERVICE_KEY='{ "serviceurls": { "AI_API_URL": ...' * Lookup service-key credentials as explained in the previous step for `AICORE_SERVICE_KEY`. -
Define a new destination in the _SAP BTP Destination Service_ using the service-key credentials. - +*
Define a new destination in the SAP BTP Destination Service using the service-key credentials + * (Destinations can be added on subaccount level and on service instance level.) * (The URL field requires an additional path segment: `/v2`) - * Name: _my-aicore_ - * Type: HTTP - * URL: _[serviceurls.AI_API_URL]/v2_ - * Proxy-Type: Internet - * Authentication: _Oauth2ClientCredentials_ - * Client ID: _[clientid]_ - * Client Secret: _[clientsecret]_ - * Token Service URL Type: Dedicated - * Token Service URL: _[url]_ - -
- -* In the application at runtime the following can be executed: + * **Name**: _my-aicore_ + * **Type**: HTTP + * **URL**: _[serviceurls.AI_API_URL]/v2_ + * **Proxy-Type**: Internet + * **Authentication**: _Oauth2ClientCredentials_ + * **Client ID**: _[clientid]_ + * **Client Secret**: _[clientsecret]_ + * **Token Service URL Type**: Dedicated + * **Token Service URL**: _[url]_ + +
+ +* At application runtime the following can be executed: ```java Destination destination = DestinationAccessor.getDestination("my-aicore"); ApiClient client = Core.getClient(destination); From eefc81cc6e6b1d5abc22293c4612d5b5c1222633 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Alexander=20D=C3=BCmont?= Date: Tue, 3 Sep 2024 11:16:40 +0200 Subject: [PATCH 3/3] Add suggested changes --- README.md | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/README.md b/README.md index c3988075f..a72998dd7 100644 --- a/README.md +++ b/README.md @@ -414,9 +414,9 @@ For more customization, creating a [HeaderProvider](https://sap.github.io/cloud- ## Requirements and Setup for AI Core -For any AI Core service interaction, the SAP Cloud SDK for AI requires credentials to be available at application runtime. +For any AI Core service interaction, the SAP AI SDK requires credentials to be available at application runtime. By default, the credentials are extracted automatically from a service instance of type "aicore" bound to the application. -Running the application locally without such service binding will throw an exception: +Running the application locally without this service binding will throw an exception: ``` Could not find any matching service bindings for service identifier 'aicore' @@ -426,16 +426,15 @@ There are multiple options to register the service binding: * Regular service binding in SAP BTP Cloud Foundry (resulting in `VCAP_SERVICES` env var entry). * Set an environment variable explicitly: `AICORE_SERVICE_KEY` * Define and use a _Destination_ in _BTP Destination Service_. -* Leveraging `"user-provided"` service binding (currently not recommended). -* Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` declaration in application (not recommended). +* (For CAP applications) use the [hybrid testing](https://cap.cloud.sap/docs/advanced/hybrid-testing#services-on-cloud-foundry) approach _(not recommended for production)_. + * For example: `cds bind --to aicore --exec mvn spring-boot:run` +* Leveraging `"user-provided"` service binding _(not recommended for production)_. +* Define and use a custom `ServiceBinding` or `ServiceBindingAccessor` declaration in application _(not recommended for production)_. ### Regular service binding in SAP BTP Cloud Foundry -* In the _SAP BTP Cockpit_ navigate to the target application. - Go to _Service Bindings_ and click _Bind Service_. - In the wizard create or bind an existing service instance of type `aicore`. -* (Or) use `manifest.yaml` to add the service binding declaratively. -* (Or) use the CF CLI to add the service binding via command line. +* Bind an existing service instance of type `aicore` to your application. + [With SAP BTP multiple options are available](https://help.sap.com/docs/btp/sap-business-technology-platform/binding-service-instances-to-applications): using the web interface, the CLI, MTA or manifest.
After application restart, there should be an "aicore" entry in environment variable VCAP_SERVICES.