Application Development Discussions
Join the discussions or start your own on all things application development, including tools and APIs, programming models, and keeping your skills sharp.
cancel
Showing results forΒ 
Search instead forΒ 
Did you mean:Β 

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

qmacro
Employee
Employee

(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:

core-services-apis.png

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:

directory-operations-endpoints.png

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

get-directory-endpoint.png

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:

  1. create an instance of the SAP Cloud Management Service, with a plan that contains the appropriate scope(s) that you need
  2. create a service key based on that instance
  3. use the details in the service key to request an access token
  4. 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.

service-plan-details.png

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:

basic-dev-space-with-cf-cli.png

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:

cf-api-endpoint-cockpit.png

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?

82 REPLIES 82

ajmaradiaga
Employee
Employee
0 Kudos

057e2524e63d3e78b9b49796f58370bcbe5ed40676c8542265e16a0998371793

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.

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

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

nicoschoenteich
Employee
Employee
0 Kudos

b152bfdff2edc5f99862897bc41a20c071de259c07eb47d7bb81120f1fa0be08

seVladimirs
Galactic 5
Galactic 5
0 Kudos

aa3c78e57f331a73be835d872a491757b15c82ec5016b3442689f6c7c575e32e

bztoy
Galactic 4
Galactic 4
0 Kudos

220633a2f99b57576a5f24a31b1c1bb0334afc6bcdc37040c1c9759f4286b23b

0 Kudos

A late reply to share my thought about the discussion points. I got Covid-19 on Monday, still not fully recovery yet but feel much better to be able to turn on my notebook again πŸ˜…

 

 

Is this your first encounter with the cf CLI? How did you find it?


No, it is not. I never use these CLI tools in my job (no experience in any SAP Cloud project) but I learn the basic of these tools from SAP community blog posts and SAP Developer Hands-on session like Getting started with OAuth 2.0

 

What is your favorite place to run command line tools?


A terminal with bash shell πŸ˜

In my Windows machine : Windows terminal + Bash in Ubuntu WSL

In my Fedora Linux: Just Gnome Terminal + Bash

MY WORK HERE IS DONE

kasch-code
Galactic 3
Galactic 3
0 Kudos

ed571857ef0c3a6960b444dee5bb4ff147b5b89fbb2ace1c9eea9f7fe5fe307d

stickman_0x00
Galactic 3
Galactic 3
0 Kudos

75cbe82859bdda7fba56d9458f3003fd6f8a21ebf844bb05fb5ff4cbfdf1e4df

SandipAgarwalla
Galactic 4
Galactic 4
0 Kudos

66db926f62d72794c9f27c0379bdb41c9e2105dc56acba0e121b3ee288b18913

SandipAgarwalla
Galactic 4
Galactic 4
0 Kudos

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? 

ceedee666
Galactic 3
Galactic 3
0 Kudos

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.

0 Kudos

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. 

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.

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

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:

ceedee666_0-1692617181882.png

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

ceedee666_1-1692617245215.png

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

 

 

Just out of interest, are the CF API endpoints for the two CF environments (across the two global accounts) different? What are they? But I think your move (remove email address) is probably a good idea.

0 Kudos

In the ABAP Mentors Org the Endpoint is: https://api.cf.eu10.hana.ondemand.com

In my own Org it is: https://api.cf.eu10-004.hana.ondemand.com

I also tried to login to the latter. However, my credentials don't work there.

 
 

OK, I finally found a way that worked. Logging out via accounts.sap.com and then using

cf login --sso 

does the trick

0 Kudos

Hi @qmacro, after sucessfully loging in I tried to add the entitlement for the cis service to my subaccount via the BTP CLI. I tried the following command:

btp assign accounts/entitlement --for-service cis --plan central -to-subaccount...

The command returned OK but I wasn't able to see the entitlement. After creating it in the UI I was able to see it using

btp list accounts/entitlement    

Any ideas? Dis I miss something?

dan_wroblewski
Employee
Employee
0 Kudos

cbcf2c6b1281e441f7b4bf8f80c0a50f926c3457653e068856bfc2c75b8eb0b9




--------------
See all my blogs and connect with me on Twitter / LinkedIn

Tomas_Buryanek
Galactic 4
Galactic 4
0 Kudos

b944497f61ee22ea371ddf99151f64bda08b277e66c541e6c6c012e9718097d1

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 πŸ™‚

Great, at least you've now had the chance to give it a go πŸ‘

cdias
Employee
Employee
0 Kudos

d6116ab565c82fd35317633beb51b721523c61e6a21e8a069a8e0722c01d0aeb

abdullahgunes
Galactic 3
Galactic 3
0 Kudos
96d1b231260cefd9f9cf3d7aae0ca4c6111006771ad0963613d4a36be481ddb5

ceedee666
Galactic 3
Galactic 3
0 Kudos
2a010a231ebbee695aae2071cb26baac428893cd9c62c5ba0ae3a52a6ddfc670

salilmehta01
Employee
Employee
0 Kudos

eb04e8f4b2dd6c62299033d289f0ead6eec5504ea684c0d095494d3f84105f9c

anupamduttaroy
Galactic 4
Galactic 4
0 Kudos

Hi, Could you please help me to understand what I might be missing. I am using central plan; but receiving the following 403 error while trying out from business accelerator hub. I am trying to get the directory information, authorization is enabled already for the directory. 

anupamduttaroy_0-1692691359418.png

-Anupam

0 Kudos

Hi there. Can you tell me what you're trying to do here? The task here has no requirement that you use the hub, so I'm a little lost.

0 Kudos

Hi DJ,

I tried with postman too to get the directory information; it gives me same 403 error:

anupamduttaroy_1-1692764832567.png

 

I Created cloud management service instance with central plan. Tried with both password and client credential tokens. Every time I am getting this error. Not sure what I am missing.

-Anupam

0 Kudos

@qmacro I understand this is not part of the task, I wanted to explore the APIs as well. But, I am surely missing something. 😞

Aha, that's great! In fact, don't worry - we'll be getting to making a call to the API in a future task in this challenge. So watch this space! πŸ™‚

Nicolas
Galactic 3
Galactic 3
0 Kudos

780b2eabdd1959d8c48a43390eaeef27182769c770e3a1139619732466584320

shotokka
Galactic 3
Galactic 3
0 Kudos

53b8ef74bb1cd2f78fcc09b1faab9f4df83520c57ce77d5414621f19e24a9b1b

PriyankaChak
Galactic 3
Galactic 3
0 Kudos

cacfcb2ab2f26b9d11c7c6092ddb241b75fa6339bb2dc82c6026cc3854023ab6

thomas_jung
Employee
Employee
0 Kudos

45c770a8d90b7039bc50ad66e703e74a86ed19056a252b79d970c353e800c7bd