title | titleSuffix | description | ms.service | author | ms.author | ms.topic | ms.date | ms.custom |
---|---|---|---|---|---|---|---|---|
Import an SAP API using the Azure portal | Microsoft Docs |
Learn how to import OData metadata from SAP as an API to Azure API Management |
api-management |
martinpankraz |
mapankra |
how-to |
01/26/2022 |
This article shows how to import an OData service using its metadata description. In this article, SAP Gateway serves as an example. However, you can apply the approach to any OData-compliant service.
In this article, you'll:
[!div class="checklist"]
- Convert OData metadata to an OpenAPI specification
- Import the OpenAPI specification to API Management
- Complete API configuration
- Test the API in the Azure portal
-
An existing API Management instance. Create one if you haven't already.
-
An SAP system and service exposed as OData v2 or v4.
-
If your SAP backend uses a self-signed certificate (for test purposes), you may need to disable the verification of the trust chain for SSL. To do so, configure a backend in your API Management instance:
- In the Azure portal, under APIs, select Backends > + Add.
- Add a Custom URL pointing to the SAP backend service.
- Uncheck Validate certificate chain and Validate certificate name.
[!NOTE] For production scenarios, use proper certificates for end-to-end SSL verification.
-
Retrieve metadata XML from your SAP service. Use one of these methods:
- Use the SAP Gateway Client (transaction
/IWFND/GW_CLIENT
), or - Make a direct HTTP call to retrieve the XML:
http://<OData server URL>:<port>/<path>/$metadata
.
- Use the SAP Gateway Client (transaction
-
Convert the OData XML to OpenAPI JSON format. Use an OASIS open-source tool for OData v2 or OData v4, depending on your metadata XML.
The following is an example command to convert OData v2 XML for the test service
epm_ref_apps_prod_man_srv
:odata-openapi -p --basePath '/sap/opu/odata/sap/epm_ref_apps_prod_man_srv' \ --scheme https --host <your IP address>:<your SSL port> \ ./epm_ref_apps_prod_man_srv.xml
[!NOTE]
- For test purposes with a single XML file, you can use a web-based converter based on the open-source tool.
- With the tool or the web-based converter, specifying the <IP address>:<port> of your SAP OData server is optional. Alternatively, add this information later in your generated OpenAPI specification or after importing to API Management.
-
Save the
openapi-spec.json
file locally for import to API Management.
[!INCLUDE api-management-navigate-to-instance]
-
From the side navigation menu, under the APIs section, select APIs.
-
Under Create a new definition, select OpenAPI specification.
:::image type="content" source="./media/import-api-from-oas/oas-api.png" alt-text="OpenAPI specifiction":::
-
Click Select a file, and select the
openapi-spec.json
file that you saved locally in a previous step. -
Enter API settings. You can set the values during creation or configure them later by going to the Settings tab.
-
In API URL suffix, we recommend using the same URL path as in the original SAP service.
-
For more information about API settings, see Import and publish your first API tutorial.
-
-
Select Create.
Note
The API import limitations are documented in another article.
Add the following three operations to the API that you imported.
-
GET /$metadata
Operation Description Further configuration for operation GET /$metadata
Enables API Management to reach the $metadata
endpoint, which is required for client integration with the OData server.
This required operation isn't included in the OpenAPI specification that you generated and imported.Add a 200 OK
response.:::image type="content" source="media/sap-api/get-metadata-operation.png" alt-text="Get metadata operation":::
-
HEAD /
Operation Description Further configuration for operation HEAD /
Enables the client to exchange Cross Site Request Forgery (CSRF) tokens with the SAP server, when required.
SAP also allows CSRF token exchange using the GET verb.
CSRF token exchange isn’t covered in this article. See an example API Management policy snippet to broker token exchange.N/A :::image type="content" source="media/sap-api/head-root-operation.png" alt-text="Operation to fetch tokens":::
-
GET /
Operation Description Further configuration for operation GET /
Enables policy configuration at service root. Configure the following inbound rewrite-uri policy to append a trailing slash to requests that are forwarded to service root:
<rewrite-uri template="/" copy-unmatched-params="true" />
This policy removes potential ambiguity of requests with or without trailing slashes, which are treated differently by some backends.:::image type="content" source="media/sap-api/get-root-operation.png" alt-text="Get operation for service root":::
Also, configure authentication to your backend using an appropriate method for your environment. For examples, see API Management authentication policies.
-
Navigate to your API Management instance.
-
From the side navigation menu, under the APIs section, select APIs.
-
Under All APIs, select your imported API.
-
Select the Test tab to access the test console.
-
Select an operation, enter any required values, and select Send.
For example, test the
GET /$metadata
call to verify connectivity to the SAP backend -
View the response. To troubleshoot, trace the call.
-
When testing is complete, exit the test console.
- See an example end-to-end scenario to integrate API Management with an SAP gateway.
- Control access to an SAP backend using API Management policies. See policy snippets for SAP principal propagation and fetching an X-CSRF token.
- For guidance to deploy, manage, and migrate APIs at scale, see:
[!INCLUDE api-management-define-api-topics.md]
[!div class="nextstepaction"] Transform and protect a published API