diff --git a/README.md b/README.md index f0d078e4..972872de 100644 --- a/README.md +++ b/README.md @@ -478,14 +478,55 @@ 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 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 this 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_. +* (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 + +* 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. + +```json +{ + "aicore": [ + { + "clientid": "...", + "clientsecret": "...", + "url": "...", + "identityzone": "...", + "identityzoneid": "...", + "appname": "...", + "serviceurls": { + "AI_API_URL": "..." + } + } + ] +} +``` + +
+ +### Set credentials as dedicated environment variable - `Could not find any matching service bindings for service identifier 'aicore'` -- Go into the BTP Cockpit +- 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 @@ -494,7 +535,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]_ + +
+ +* At application 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