Azure SDK for SAP OData 🚀 (PREVIEW)

Use this repos to enable services like Azure Functions <⚡> to consume SAP OData services and work with plain-old-class-objects (POCO) without any dependencies on other libraries.

Marshalling the OData semantics into the SDK reduces initial integration effort and allows developers to focus on business logic quicker.

Currently supported output language is C#. You may extend by adding templates for other languages here. Consumers of the SDK can be coded in any language.

Note

Due to the nature of the SDK it can be applied to apps or functions coded in NodeJS too.

Note

In case you prefer SAP's own Cloud SDK for your Azure app development, have a look at this sister project deploying to Azure App Service and Azure Functions. Another option is the SAP Cloud Application Programming model showcased on this repos.

Prerequisites 👨🏾‍🎓

• Azure Subscription
• Local Development setup with Dotnet 6 and Azure Functions Core tools v4 or to hit the ground running without any further need for setup.
• Any OData Service (for example SAP Mock Server, SAP Demo Gateway (OData Catalog Service), S/4HANA Cloud, SAP API Business Hub, SAP SuccessFactors, S/4HANA Fully-Activated appliance from SAP CAL, your own in-house SAP system, etc.)

Note

The SAP mock server is a separate project and not part of this repo. You can find the mock server here.

Note

You can use the SAP API Business Hub to get a free trial of SAP OData services or leverage the public demo system ES5. Find the GWSAMPLE_BASIC demo service on ES5 here. See SAP's blog post about ES5 for more details and how to request a user.

Getting Started 🚀

• Get your OData service metadata as file or URL
• git clone https://github.com/Azure/azure-sdk-for-sap-odata.git
• Feed your OData metadata to the supplied generator. Learn more about the generator here

For Windows

cd azure-sdk-for-sap-odata\BinaryDownloads
Expand-Archive DataOperations.Generator.OData_win-x64.zip C:\Generator
cd C:\Generator\publishout
.\DataOperations.Generator.OData.exe --inputfile C:\Generator\publishout\metadata.xml --outputfolder C:\SDK --templatefolder C:\Generator\publishout\Templates --samples true

For Linux

cd azure-sdk-for-sap-odata/BinaryDownloads
unzip DataOperations.Generator.OData_linux-x64.zip -d /workspaces/Generator
cd /workspaces/Generator/publishout
chmod +x DataOperations.Generator.OData
chmod -R 777 /workspaces/Generator/publishout
./DataOperations.Generator.OData --inputfile /workspaces/Generator/publishout/metadata.xml --outputfolder /workspaces/SDK --templatefolder /workspaces/Generator/publishout/Templates --samples true

For Mac

We support Mac with both x86 and ARM architectures. For x86, generate the SDK using:

cd azure-sdk-for-sap-odata/BinaryDownloads
unzip DataOperations.Generator.OData_osx-x64.zip -d /workspaces/Generator
cd /workspaces/Generator/publishout
chmod +x DataOperations.Generator.OData
chmod -R 777 /workspaces/Generator/publishout
./DataOperations.Generator.OData --inputfile /workspaces/Generator/publishout/metadata.xml --outputfolder /workspaces/SDK --templatefolder /workspaces/Generator/publishout/Templates --samples true

Or below steps to generate SDK for ARM (macOS 13 Ventura) architecture. you can check macOS runtime identifier to get target name for different version, and follow build from source to build binary files.

cd azure-sdk-for-sap-odata/BinaryDownloads
unzip DataOperations.Generator.OData_osx.13-arm64.zip -d /workspaces/Generator
cd /workspaces/Generator/publishout
chmod +x DataOperations.Generator.OData
chmod -R 777 /workspaces/Generator/publishout
./DataOperations.Generator.OData --inputfile /workspaces/Generator/publishout/metadata.xml --outputfolder /workspaces/SDK --templatefolder /workspaces/Generator/publishout/Templates --samples true

• Enjoy the Microsoft + SAP ASCII chart and find the .NET SDK for your OData service in your specified folder C:\SDK.

• Get started with provided Function App sample in C:\SDK\Samples\FunctionsSample.GWSAMPLE_BASIC.

• Maintain respective local.settings.json with your SAP OData service setup and credentials. Have a look at the provided sample file 'local.settings_sample.json'.

• Open the solution in Visual Studio or Visual Studio Code.

• cd C:\SDK making sure the Dependencies and GWSAMPLE_BASIC folder are present and compiled.

• cd .\Samples\FunctionsSample.GWSAMPLE_BASIC\

• Execute func host start and start coding😎👌🔥

  [!Note] In case the func host start shows the error error NU1100: Unable to resolve ... execute the command dotnet restore and then redo the func host start.

• Call http://localhost:7071/api/Products/10 to see the generated OData service in action listing the first 10 products.

• Use provided call library with VS Code REST Client for convenience.

Note

Adjust to https://your-gh-domain.preview.app.github.dev/api/Products/10 for Codespaces.

Learn more about the local Azure Functions start commands per project language here.

Note

Use the TestClient sample for local execution without Azure Functions environment in case you are looking for a generic implementation.

How to use with Azure Functions <⚡>

Have a look at the SAPBindingDemo.cs file to learn more about the generated SDK and how to use it in Azure Functions.

• http Trigger: specifies the http method and route (e.g. /Products/{param})
• SAP Input Binding: enables complex pre-flight requests for SAP business objects and functions served by the OData service setting the scene for the actual request. This simplifies the request structure and puts focus on the business logic.
• SAP Output Binding: enables complex post-processing of the SAP business object altered in the function, marshalling the required OData call to finish the request.

Note

The described approach in this repos is applicable to other Azure PaaS offerings like Azure App Service. See the Azure App Service SAP Cloud SDK quickstart for JavaScript for reference.

Deploy to Azure🪂

There are multiple ways to deploy this project to Azure. We provide two options in this repository:

1. via template deployment and VS Code extension - more information is available here
2. via Azure Developer CLI using azd up - more information is available here soon and tracked in Issue 1

Understand your generated SDK structure🫀

You get two folders in your output folder. One containing the helper classes always named "Dependencies" and the other containing the individually generated classes for your OData service. The sub folder WebJobs refers to the Azure Functions bindings.

Learn more about the generated SDK structure here.

Advanced: Modify the SDK / then build from source and generate your own SDK generator

You can modify the SDK or outputs and dependencies to add new features and functions then generate and publish your own binaries folder. To fire the generation, you can use the same build scripts that we do, just follow the steps here.

Note

You will need a Windows machine or container ready to run the generate SDK scripts

1. Open a command line terminal
2. Clone the repository.
3. Cd into the root of the cloned folder
4. Create another folder to contain the output (outside of the repo folder)
5. Run the master build script to trigger the build, using the full path to the created output folder by running publishtobinariesfolder.cmd

Example to custom build SDK GENERATOR

md c:\source
md C:\SAPSDKBuildOutput
cd c:\source
git clone https://github.com/Azure/azure-sdk-for-sap-odata.git
cd azure-sdk-for-sap-odata
C:\Source\azure-sdk-for-sap-odata>buildandpublish\publishme.cmd c:\SAPSDKBuildOutput

Once this is completed, your built outputs should be in the folder C:\SAPSDKBuildOutput\BinaryDownloads for you to follow the above instructions.

Note that the script that the script testbuildsdkandsamples.cmd will build the SDK Generator, extract the windows-x64 binaries and then run the samples to test the SDK Generator works you might find this useful if modifying the SDK or template files.

What's next?

You can do a lot more once the app is deployed. Curious? We go you covered with some more information here

Troubleshooting 🩺

• Access SAP Gateway logs in /IWFND/ERROR_LOG
• Azure Functions diagnostics
• Use Kudu SSH console from VNet integrated App Service to check connectivity to SAP Gateway with curl https://<your domain>:<your https port>/sap/opu/odata/sap/API_BUSINESS_PARTNER -u "<user>:<password>"
• Azure API Management Request tracing
• Azure API Management Gateway logs

Additional resources

We compared to existing OpenAPI projects, collected additional resources, related efforts and projects here.

Contributing👩🏼‍🤝‍👨🏽

This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.opensource.microsoft.com.

When you submit a pull request, a CLA bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., status check, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.

This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.

Trademarks™

This project may contain trademarks or logos for projects, products, or services. Authorized use of Microsoft trademarks or logos is subject to and must follow Microsoft's Trademark & Brand Guidelines. Use of Microsoft trademarks or logos in modified versions of this project must not cause confusion or imply Microsoft sponsorship. Any use of third-party trademarks or logos are subject to those third-party's policies.