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
Developer Advocate
Developer Advocate

(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

szeteng00
Explorer
0 Kudos

3481a26997084d43cc998afbb003cafb8341af8e8b2ba22f5bcfb9939613c5b0

ADR
Participant
0 Kudos

2acf622e9246e73abf90a5eac51b8319bf8f11d079d54f8c02f966cf211a85e7

ADR
Participant
0 Kudos

By the way, I could not filter the cloud management service instance using -d 'q=name:<myinstancename>' In windows it returned all the services in the entire global account and in linux it threw an error with code 10001.

Appreciate if anyone can help me to understand what exactly I am missing?

-Anupam

qmacro
Developer Advocate
Developer Advocate
0 Kudos

You'll need to provide a bit more information, on (a) what you're trying to do exactly ("filter the cloud management service instance"?) and (b) more detail on the errors πŸ‘

harsh_itaverma
Participant
0 Kudos

3f97dac1539260e4cf1920b0150bcfc7a380291deaaa23a408677ce2aa74bb4d

Ashok459
Participant
0 Kudos

f721a0ef2abef7e3c0c99929e682d820ef05d70bd678180ca772bfe77783a7d0

UweFetzer_se38
Active Contributor
0 Kudos

66d85963c3df584e028f018d25588461280024f75b216c1ba08fa13071e29804

Did it with CLI, but "Terminal (still) isn't the future" πŸ˜ˆ

πŸ™‚ I know each of us has our preferences and our passion, and I respect that 

 

choujiacheng
Explorer
0 Kudos

ac98cac1fe34e467ae6fe1316c1271401d8107e6e2b4e5c6420d51bc75ab80d1

0 Kudos

As this is my first time using CF CLI, I find the process to be quite a challenge to get used to it, especially as I was used to adding service instances in the service marketplace through the CF GUI, but a Google search did eventually lead to the solution. I was also kicking myself for nearly an hour to finish this task, turns out I was not supposed to read the directory GUID from the API just yet. I usually prefer to use Windows' default command line interface, but for this case, I would rather use the command line in BAS since it means I can run it without installing the program natively.

qmacro
Developer Advocate
Developer Advocate

Thanks for sharing your thoughts, @choujiacheng ! In a way, I find that a bit of a struggle to get things working does help in the long term, because the peripheral work one does to figure out what to do is also part of the learning process. I'm glad you got there!

I'm a massive fan of the power of the command line, which in turn means (for me) a UNIX style shell, with all that goodness that the UNIX philosophy entails (small well behaved programs that do one thing well, and a beautiful STDIN/STDOUT/STDERR and pipe model for glueing these programs together). One of my favourite aspects of BAS is that the Dev Spaces give you a proper command line with such a shell (Bash, to be precise, The One True Shell(tm) ;-))

tobiasz_h
Active Participant
0 Kudos

08a0709148eeca2d23b6e4e546fcc7afc4666075e68a608b352408875174a42d

garyzuo
Explorer
0 Kudos

54936765391f057b6d06ddcfd59a2942379c8b10b5848e45b05df425f878ef56

prachetas
Participant
0 Kudos

84be9815fa637c25f3286de21128842ec06f074ab41dd617a48e31b516533e91

geek
Explorer
0 Kudos

286e6e9814755fec3807761a60e5f7f929fb2d264f7065d21950e4f9497944e5

former_member136915
Product and Topic Expert
Product and Topic Expert
0 Kudos
41709c36a732dcd7c97fc3dbebc6ba9dcce6df7a228591e0144bfef14f18715e

tly
Explorer
0 Kudos

4cc30b2ba5b67aee91ab048911c70b97b8de8cb411c235cd881af3b173752232

emiliocampo
Explorer
0 Kudos

e75592928568d3393d49c90d34152c6ef8f7f1e64e4f4119cb902c652aeea499

berserk
Explorer
0 Kudos

c8971320b385e6c08a145bef16c9a04ef8b5db89a4ad6c55b82ae83e280671e8

sabarna17
Contributor
0 Kudos

16631dc253766ecf52da94cba9ad3d2b133583c6d475164d465c8809c9314db0

I generally use cf-cli to deploy  node/python applications. But  I havn't tried to manage service instances before. This task gave me some idea on  CF8-CLI for Infra deployments. 

Using Node-Red is always fun. And all the CF8 deployments / Service Managments can be easily scaled and automated as well using Node-red. Here we can automate a server to perform a CLI based task easily through HTTP Injections as well. I have just tried out something -

sabarna17_0-1693204809650.png

In this Node-Red Flow, I have added a HTTP Request IN Node - "/cis_service_entity_type". Now this becomes a API which I can consume..

sabarna17_2-1693204926212.png

Ruthiel
Product and Topic Expert
Product and Topic Expert
0 Kudos

8be5843d671d1f41b3d85f0e94fa9153ed089d62f5cf226a205658c2fff71a86

MarcelloUrbani
Active Contributor
0 Kudos

f7b361341ffdc53b594cf54ebc9057dac5ae3e097e6b12e8c7b346d3b2f4b61a

Struggled quite a bit to get the CF login via API, documentation is pretty hard to find

This works:

POST https://uaa.cf.us10-001.hana.ondemand.com/oauth/token
Content-Type: application/x-www-form-urlencoded
Authorization: Basic cf:

grant_type=password
&username={{$dotenv CIS_USER}}
&password={{$dotenv CIS_PASSWORD}}
 
 

martinstenzig
Contributor
0 Kudos

6f208375d358491da792f88ec2a45427c3e1a75e31f1bcfc08911fd5a73d55b4

0 Kudos

@qmacro , great exercise. cf curl is certainly something I didn't know would work.
Here is a question for you though: In Task 1, why does the client credentials authentication in task one have a different scope (only uaa.resources) than the password type? I tried specifying the scope explicitly, but didn't get anywhere. 

johna69
Product and Topic Expert
Product and Topic Expert
0 Kudos

d660fc6486694e71156e81cc1baf882b0b40d1c97e811bd0e264d4fd15b234db

ecem_yalim
Explorer
0 Kudos

9eed6fac6f3b0b019efe4c7ce62d3e9868d07fb2517d1783502cb099b265dcd8

cguttikonda24
Participant
0 Kudos

68d0a8e218ac10fc8d82a63ec43b5e3ba7535cadf7e68819a24b54a043444832

nex
Explorer
0 Kudos

8e979313b59017c3f1cc8222c4c34d182a2939585dccc30a272576bbcff28abd

RafkeMagic
Active Contributor
0 Kudos

37c227a79bb81cceccd1249ca9c1626791233d7a07707f4543052885b2ff7f52

flo_conrad
Explorer
0 Kudos

15e613757c3bc582c6d9562071aece69b59725d6eae0be881e5054ea26eee426

RaulVega
Participant
0 Kudos

4e197c1c6825fd370f9b5e45333a16f63c417499932f19931da470c645969ee7

dhegde
Participant
0 Kudos

913411eb29e62ffa0643f28fe8593574083d98ab5e22ad8020c15c0d90ffb9f0

andrew_chiam
Explorer
0 Kudos

7de51987662eb837f86fe970d49109fb0e1e9b92f305ba4a59443bcf10a5390f

OlgenH
Participant
0 Kudos

4f66028f426ecd507d8ac43cbbf317cc9777bd0d4c30b5869ae1b9fdd2dde63e

qmacro
Developer Advocate
Developer Advocate
0 Kudos

Hey everyone! The challenge to which this task belongs is now officially closed. Head over to the original blog post SAP Developer Challenge – APIs to check out the closing info and final statistics, and to see your name in lights! πŸŽ‰  And we thank you all for participating, you made this challenge great!

devrajsinghr
Active Participant
0 Kudos

a681e90194e977989b782a22769a28bfffa9f1816c5b52e3ad1d61533d48ed35

adrian-ngo
Explorer
0 Kudos
27c01ea63bdf0f60ed0f075734d558cb56a3e7461007a884ff60a16e7cfd914d