topic Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service in Application Development and Automation Discussions

SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

qmacro — Mon, 21 Aug 2023 05:56:05 GMT

(Check out the SAP Developer Challenge - APIs blog post for everything you need to know about the challenge to which this task relates!)

In this task, you're going to create an instance of the SAP Cloud Management Service, with a specific plan. To find out why, read on.

Background

This task follows on from and is in a group with the previous task (Task 7 - Create a new directory in an SAP BTP account). Having created a directory in your SAP Business Technology Platform (SAP BTP) account, you're going to eventually retrieve that directory's details programmatically, through an API endpoint.

In making such a call to the appropriate endpoint, you need to supply authentication details in the HTTP header.

What do the authentication details look like, and how do you obtain them? Well, in this and subsequent tasks, you'll find out, by reading, and by doing!

The details of the API endpoint

On the reading part, you should start out by jumping back to the Core Services for SAP BTP API package landing page on the SAP Business Accelerator Hub that you viewed in the previous task. You'll see a range of APIs, like this:

The Accounts Service API is described thus: "Manage the directories and subaccounts in your global account's structure". This is the API containing the endpoint that you'll eventually use to look at the details of the directory you created in the previous task.

Selecting this API, and navigating to its API Reference section, specifically to the Directory Operations group, you'll see quite a list of endpoints, some of which you can see in this screenshot:

One of them is the one you'll eventually be calling:

Note that the final part of the endpoint's path, {directoryGUID}, is what we need to specify when making a call to this endpoint. Remind you of anything? Yes, it's the GUID value of your newly created directory that you determined in the previous task.

While you're staring at the details of this endpoint, make a mental note of this part:

Required scope: $XSAPPNAME.global-account.account-directory.read

This will become relevant shortly.

The documentation on this API

While you're still in reading mode, jump back to the Accounts Service API Overview and follow the link to the SAP Help Portal documentation Account Administration Using APIs of the SAP Cloud Management Service. It's here that you'll find information on setting up for calls to this API and its endpoints. Take some time to read through the linked section and the subsections within.

Here's a very brief summary of what it says, so you have something concise to which you can refer in this and subsequent tasks in this group.

In order to make calls to API endpoints in this API (and indeed the other APIs in the package), you'll need to follow these steps:

create an instance of the SAP Cloud Management Service, with a plan that contains the appropriate scope(s) that you need
create a service key based on that instance
use the details in the service key to request an access token
use the access token thus obtained to authenticate a call to the API endpoint

The documentation mentions different environments in which you might create an instance of the service; for the purposes of this Developer Challenge as a whole, please use a Cloud Foundry environment. This is for a couple of reasons:

everyone can get a Cloud Foundry environment on SAP BTP; for example, if you're using a trial account you will most likely have a Cloud Foundry environment automatically set up for you in your subaccount, and if you don't have one, you can create one
it makes running this task and the related tasks simpler and we can all take part in the same collective and shared conversation about what we're doing

OK, let's look at precisely what your task is. That list of steps above looks quite a lot of work ... but don't worry. Your task today relates only to step 1 in the list.

Your task

There are two parts to your task here. In both parts, you should use the cf command line tool for Cloud Foundry (also known as the "cf CLI").

There are different ways you could go about creating a service instance on Cloud Foundry, but here the cf CLI is prescribed because it can be used for not only creating the instance, but also for retrieving detailed information afterwards. And of course, also because #TheFutureIsTerminal 🙂

For part one, you must complete step 1 in the list above, i.e. create an instance of the SAP Cloud Management Service (short name: cis). Do this in your SAP BTP account that you used in the previous task. Make sure you choose the appropriate plan when doing this, and create the instance in your Cloud Foundry environment.

Information on where to find the service plan details, and tips on how to create the instance itself, are detailed in the "Hints and tips" section.

For part two, you must use the Cloud Foundry API to retrieve information about your newly created service instance. Specifically, you should use the List all Service Instances endpoint (GET /v2/service_instances). And as you'll have already been using the cf CLI for part one of this task, you are strongly encouraged to use it for this part as well. Did you know that you can use the cf CLI to make calls to the CF API as well? Find out more in the "Hints and tips section below".

From the information you retrieve via the GET /v2/service_instances endpoint, you should identify the appropriate object in the resources property in the JSON returned, and pick out the value of the entity type.

Here's an example (with some properties removed for brevity):

{
  "total_results": 1,
  "resources": [
    {
      "metadata": {
        "guid": "58314563-ab6d-48db-b40c-ae4abf0e0355",
        "url": "/v2/service_instances/58314563-ab6d-48db-b40c-ae4abf0e0355",
        "created_at": "2023-08-15T10:31:13Z",
        "updated_at": "2023-08-15T10:31:15Z"
      },
      "entity": {
        "name": "cis-central",
        "credentials": {},
        "service_plan_guid": "7cc70093-3c5f-47f2-acf6-8de4185ba63c",
        "space_guid": "52311e40-efaa-4176-bef1-505f3a9889bd",
        "gateway_data": null,
        "dashboard_url": null,
        "type": "<instance-type>",
        "last_operation": {
          "type": "create",
          "state": "succeeded",
          "updated_at": "2023-08-15T10:31:15Z",
          "created_at": "2023-08-15T10:31:15Z"
        },
        "tags": [],
        "maintenance_info": {},
        "service_guid": "4eacd0ef-9a9d-4cb3-8fb1-60fb685d8f82"
      }
    }
  ]
}

As you can see in this example, there's only one service instance in the Cloud Foundry environment org / space used to set up this example. This is reflected in the fact that there's only a single object contained in the resources array. That object represents and contains the details of that service instance.

The type of the service instance is given in the entity.type property within the object. In the example above, the value is deliberately hidden, and has been replaced by the string <instance-type>.

For those of you who are curious and have also tried to use cf service to list details of the service, note that the entity type shown in the output to cf service is not quite the same, and not what is required here. You have been warned!

It's the actual value of this entity.type property that you must determine and send to be hashed and shared in a reply to this discussion thread as described in Task 0. So whatever that value is, in the JSON that's returned, that's what you need to send to be hashed (don't include the double quotes, because they're just part of the JSON syntax of course).

Hints and tips

Here are some pointers to help you with this task.

Creation of the service instance

If you read through the Account Administration Using APIs of the SAP Cloud Management Service documentation, you will have come across the SAP Cloud Management Service - Service Plans section. In this section, the details of each service plan offered are available, including a list of scopes provided by each.

When creating the service instance, make sure you specify the appropriate plan, the plan that contains the scope that you need to make a GET request to the /accounts/v1/directories/{directoryGUID} API endpoint.

Using the cf CLI

You are required to use the cf CLI for both parts of this task. Some of you may already have the cf CLI installed. Others may not.

For those of you who have it installed, or are willing and able to install it in their own system, we recommend you use the latest major version, i.e. version 8. The reason for this is twofold:

the major version of the cf CLI available in all Dev Spaces in the SAP Business Application Studio is 8 (specifically, at the time of writing, version 8.5.0+73aa161.2022-09-12)
there are some breaking changes introduced between major versions 7 and 8, including in the area of the output of service binding details, so it's best that we're all on the same version and we also recommend you move to 8 now anyway

See Upgrading to cf CLI v8 for details of what's new and different with version 8.

For those who don't already have the cf CLI installed, and don't want to install it right now, we recommend you make use of a Dev Space in the SAP Business Application Studio. Just like the Cloud Foundry environment itself, a subscription to the SAP Business Application Studio is available to anyone and everyone, not least within a trial SAP BTP account context. You can follow the tutorial Set Up SAP Business Application Studio for Development if you need some guidance on getting access.

Once you have a subscription to the SAP Business Application Studio, create yourself a Dev Space. It doesn't have to be anything special - even a Basic Dev Space contains the cf CLI, as you can see:

Once you have a Dev Space up and running, and you have of course opened up a terminal session therein (use menu path "Terminal -> New Terminal"), you have the cf CLI at your disposal.

At this point you should log in, and specify the API endpoint that relates to your specific Cloud Foundry environment instance.

There are different ways to find out what the API endpoint is (including programmatically, see Determining your CF API endpoint), but a simple way for the purposes of this task is to head over to the SAP BTP Cockpit and check in the subaccount overview:

Once you've logged in, you'll need to familiarize yourself with the cf CLI commands related to this task.

For the first part of the task, look into the "Services integration" commands (get to this list using the command cf help):

Services integration:
  marketplace,m        create-user-provided-service,cups
  services,s           update-user-provided-service,uups
  create-service,cs    create-service-key,csk
  update-service       delete-service-key,dsk
  delete-service,ds    service-keys,sk
  service              service-key
  bind-service,bs      bind-route-service,brs
  unbind-service,us    unbind-route-service,urs

In particular:

cf marketplace will give you a list of service offerings; specifying a particular service offering with the -e option is also worth looking into
cf create-service will allow you to create a new service instance, specifying the plan as well as the service
cf services will allow you to list services instances that already exist, allowing you to check that your service instance creation was successful

When using cf marketplace, note that the service offerings will be listed using their technical name. The technical name for the SAP Cloud Management Service is cis, as noted in the Account Administration Using APIs of the SAP Cloud Management Service section on the SAP Help Portal.

For the second part of the task, you'll want to look at:

cf curl

Interestingly, if you want to find this command in the list of possible commands in the cf CLI, you must use:

cf help -a

(i.e. include the -a option) otherwise it's not shown.

Good luck and have fun!

For discussion

How else might one create an instance of a service? Is this your first encounter with the cf CLI? How did you find it? What is your favorite place to run command line tools?

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

ajmaradiaga — Mon, 21 Aug 2023 06:13:14 GMT

057e2524e63d3e78b9b49796f58370bcbe5ed40676c8542265e16a0998371793

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

ajmaradiaga — Mon, 21 Aug 2023 06:16:27 GMT

I wasn't familiar with cf curl... Thanks for highlighting this :-). It is funny how that type value for the instance is different in cf curl than what is output in cf service.

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

qmacro — Mon, 21 Aug 2023 06:28:47 GMT

You're welcome! The best thing about this challenge is that we can impart little nuggets of info like this to the wider community 👍

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

nicoschoenteich — Mon, 21 Aug 2023 06:41:39 GMT

b152bfdff2edc5f99862897bc41a20c071de259c07eb47d7bb81120f1fa0be08

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

nicoschoenteich — Mon, 21 Aug 2023 06:42:04 GMT

cf curl... sounds like something DJ's dreams are made of!

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

vladimirs_semikins — Mon, 21 Aug 2023 07:36:47 GMT

aa3c78e57f331a73be835d872a491757b15c82ec5016b3442689f6c7c575e32e

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

bztoy — Mon, 21 Aug 2023 09:28:33 GMT

220633a2f99b57576a5f24a31b1c1bb0334afc6bcdc37040c1c9759f4286b23b

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

kasch-code — Mon, 21 Aug 2023 09:35:58 GMT

ed571857ef0c3a6960b444dee5bb4ff147b5b89fbb2ace1c9eea9f7fe5fe307d

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

stickman_0x00 — Mon, 21 Aug 2023 10:14:05 GMT

75cbe82859bdda7fba56d9458f3003fd6f8a21ebf844bb05fb5ff4cbfdf1e4df

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

SandipAgarwalla — Mon, 21 Aug 2023 10:31:49 GMT

66db926f62d72794c9f27c0379bdb41c9e2105dc56acba0e121b3ee288b18913

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

SandipAgarwalla — Mon, 21 Aug 2023 10:33:33 GMT

Took a while to get used to the cli and find the required info. Finally, it worked for me.

But why cf service returns a different value for type than the get api?

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

ceedee666 — Mon, 21 Aug 2023 10:36:38 GMT

How do I switch global accounts when working with CF CLI? My email adress is associated to two global accounts. When I login with my email address always the wrong global account is selected. I can't find a way to switch global accounts.

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

SandipAgarwalla — Mon, 21 Aug 2023 10:45:49 GMT

I had the same problem. My account was linked with 2 global accounts. For one of the account, it said no orgs assigned. Had to reset the password for the other account and then I could login. Took a long while to login to the correct account.

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

ceedee666 — Mon, 21 Aug 2023 11:10:08 GMT

I tried the same. I event set the default global account. But it does not work in my case. Maybe the reason is one of the global accounts is quite old and still linked to feature set A. I just opend up a service request to get my user removed from the old account.

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

qmacro — Mon, 21 Aug 2023 11:23:44 GMT

Just curious - did you specify the appropriate CF API endpoint when logging in?
cf login -a [endpoint URL]

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

Dan_Wroblewski — Mon, 21 Aug 2023 11:25:43 GMT

cbcf2c6b1281e441f7b4bf8f80c0a50f926c3457653e068856bfc2c75b8eb0b9

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

ceedee666 — Mon, 21 Aug 2023 11:29:42 GMT

yes. I have the following setup, an old (feature set a) global account (SAP Mentors ABAP Cloud System) and a new Free Tier account.

When I log in using the UI I allways see this:

I allready specified the other global account as the default. However, this doesn't seem to have the desired effect.

When I login with the CF CLI i get this:

❯ cf l API endpoint: https://api.cf.eu10.hana.ondemand.com Email: christian.drumm@gmail.com Password: Authenticating... OK Targeted org abapcp-mentors-eu10. Targeted space Trial. API endpoint: https://api.cf.eu10.hana.ondemand.com API version: 3.140.0 user: christian.drumm@gmail.com org: abapcp-mentors-eu10 space: Trial

If I then try to get the orgs I only see this:

❯ cf o Getting orgs as christian.drumm@gmail.com... name abapcp-mentors-eu10

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

Tomas_Buryanek — Mon, 21 Aug 2023 13:24:07 GMT

b944497f61ee22ea371ddf99151f64bda08b277e66c541e6c6c012e9718097d1

Re: SAP Developer Challenge - APIs - Task 8 - Create an instance of the SAP Cloud Management Service

Tomas_Buryanek — Mon, 21 Aug 2023 13:27:45 GMT

My first encounter with cf CLI. It is cool, but I think I will not join #teamTerminal and stay in #teamGUI. But I will give CLI an another try in next steps 🙂