Analyze HAR trace when importing Function App into API Management

Background introduction

API Management allow us to import a function app as an API, the UI offers a straightforward process to import the function app as described on this Microsoft public document. However, in this article we want to go beyond and explore what actions are performed in the background, it will allow us to understand the import process better and will help us dealing with issues while importing the function app.

 

 

Steps

Please review all the steps carefully, they are executed in the following order.

Note: The easiest way to see these steps is collecting a HAR trace.

 

1- It first sends a HEAD request to Microsoft.ApiManagement provider to confirm if the API exists in APIM, (of course it returns a 404 Not Found error which is expected because the API does not exist yet), we are just about to create it.

 

2- Then it sends a PUT request to Microsoft.ApiManagement and starts creating an empty (without operations) API in APIM.

 

 

3- Then it sends a GET request to Microsoft.Web provider trying to list all the HTTP triggers that we have in the function app.

 

4- Then it sends a POST request to Microsoft.Web provider to list the function app keys.

 

5- Then it sends a PUT request to Microsoft.Web provider to create a new Host key in the Function app, with the name apim-{your Azure API Management service instance name}. The value is an autogenerated random string. (If we are importing the same function app a second time from same APIM service, this step is not performed since the host key is already created).

 

 

6- Then it sends a PUT request to Microsoft.ApiManagement provider to create a named-value pair with the name {your Azure Function App instance name}-key. The value is a copy of the host key created in the previous step. (If we are importing the same function app into APIM a second time to create another API with different name, the same name value is used, no need to create a new named value).

 

7- Then it sends a POST/batch request to Microsoft.ApiManagement provider to create a backend object in APIM with the same name of the API being created. This backend is set with the following properties: For credentials it uses a header named x-functions-key (this header name MUST NOT BE CHANGED) and the value of this header is {{functionAppName-key}} which is a reference of the he named value created before, which contains the host key. The process also set up a Runtime URL for this backend object; the URL looks like https://<functionname>.azurewebsites.net/api which is the default domain of the function app being imported in APIM.  (If we are importing the same function app to APIM a second time to create another API with different name, the same backend object is used, no need to create a new one).

 

8- Then it sends a POST/batch request to Microsoft.ApiManagement provider to create the API operations based on the HTTP triggers it got from the function app in step #3.

Note: it creates 2 operations for each function, a POST and a GET operation.

 

9- Then it sends a POST/batch request to Microsoft.ApiManagement provider to create a policy for those API operations created in previous step, the policy looks like this: <set-backend-service id=”apim-generated-policy” backend-id=”functionAppName” /> this policy references the backend object created in step #7, to make use of the backend URL and host key when sending a request to the backend function app. This policy is set at the individual operation scope for each operation created.

 

Finally, the API is created successfully with all its setting mentioned above.

As noted above, the first of the import process is to create an empty API, so if any of the subsequent steps fail, the import process will send a DELETE request to Microsoft.ApiManagement provider to undo the API created in APIM, as it was unsuccessfully configured.

There are many reasons that may cause the import process to fail, let’s review the most common ones from the below Troubleshooting scenarios:

 

Note: The function app can be imported in APIM no matter if the function app is integrated with virtual network or private endpoint.

 

Symptom	Cause	Resolution
Unable to list function app keys.	Sometimes customers deploy their Function app from Terraform, DevOps, atc. And they do not generate app keys, so it fails to import function app in APIM if not keys are there. It aslo may be an issue trying to retrieve keys from function app storage. Function runtime unreachable. Commonly you will see a 400 Bad request.	Ask customers to redeploy function apps but generating function keys. Or check if customer can list those keys from Azure portal or REST API to confirm keys are populated.
Unable to create a new host key in the function app.	A Ready-only lock in the function app avoids adding host keys. Commonly you will see a 409 Conflict error even when trying to list keys.	Ask customer to remove lock and try the deployment again.

Consideration

Please be aware that the 9 steps described above are just the main actions of our interest and note that I am importing the API without specifying Tags, Products nor Versioning, so if you import the function app and select those additional options of course you will notice more requests and actions in the trace. 

 

 

 

Continue to website...