title | description | author | ms.topic | ms.date | ms.author | ms.custom |
---|---|---|---|---|---|---|
Create and use a custom resource provider |
This tutorial shows how to create and use an Azure Custom Resource Provider. Use custom resource providers to change workflows on Azure. |
jjbfour |
tutorial |
05/06/2022 |
jobreen |
devx-track-azurecli |
A custom resource provider is a contract between Azure and an endpoint. With custom resource providers, you can change workflows on Azure. This tutorial shows the process of creating a custom resource provider. If you're unfamiliar with Azure Custom Resource Providers, see the overview of Azure Custom Resource Providers.
Note
This tutorial does not show how to author an endpoint. If you don't have a RESTFUL endpoint, follow the tutorial on authoring RESTful endpoints, which is the foundation for the current tutorial.
After you create an endpoint, you can create a custom resource provider to generate a contract between the provider and the endpoint. With a custom resource provider, you can specify a list of endpoint definitions:
{
"name": "myEndpointDefinition",
"routingType": "Proxy",
"endpoint": "https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>"
}
Property | Required | Description |
---|---|---|
name | Yes | The name of the endpoint definition. Azure exposes this name through its API under /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders /resourceProviders/{resourceProviderName}/{endpointDefinitionName} |
routingType | No | The endpoint contract type. If the value isn't specified, it defaults to "Proxy". |
endpoint | Yes | The endpoint to route the requests to. This endpoint handles the response and any side effects of the request. |
The value of endpoint is the trigger URL of the Azure function app. The <yourapp>
, <funcname>
, and <functionkey>
placeholders must be replaced with values for your created function app.
The custom resource provider contains a list of endpoint definitions modeled under the actions and resourceTypes properties. The actions property maps to the custom actions exposed by the custom resource provider, and the resourceTypes property is the custom resources. In this tutorial, the custom resource provider has an actions property named myCustomAction
and a resourceTypes property named myCustomResources
.
{
"properties": {
"actions": [
{
"name": "myCustomAction",
"routingType": "Proxy",
"endpoint": "https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>"
}
],
"resourceTypes": [
{
"name": "myCustomResources",
"routingType": "Proxy",
"endpoint": "https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>"
}
]
},
"location": "eastus"
}
Note
You must replace the endpoint values with the trigger URL from the function app created in the previous tutorial.
You can deploy the previous custom resource provider by using an Azure Resource Manager template:
{
"$schema": "http://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"resources": [
{
"type": "Microsoft.CustomProviders/resourceProviders",
"name": "myCustomProvider",
"apiVersion": "2018-09-01-preview",
"location": "eastus",
"properties": {
"actions": [
{
"name": "myCustomAction",
"routingType": "Proxy",
"endpoint": "https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>"
}
],
"resourceTypes": [
{
"name": "myCustomResources",
"routingType": "Proxy",
"endpoint": "https://<yourapp>.azurewebsites.net/api/<funcname>?code=<functionkey>"
}
]
}
}
]
}
After you create a custom resource provider, you can use the new Azure APIs. The following sections explain how to call and use a custom resource provider.
Note
You must replace the {subscriptionId}
and {resourceGroupName}
placeholders with the subscription and resource group of where you deployed the custom resource provider.
az resource invoke-action --action myCustomAction \
--ids /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/myCustomProvider \
--request-body
'{
"hello": "world"
}'
Parameter | Required | Description |
---|---|---|
action | Yes | The name of the action defined in the custom resource provider. |
ids | Yes | The resource ID of the custom resource provider. |
request-body | No | The request body that will be sent to the endpoint. |
Note
You must replace the {subscriptionId}
and {resourceGroupName}
placeholders with the subscription and resource group of where you deployed the custom resource provider.
az resource create --is-full-object \
--id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/myCustomProvider/myCustomResources/myTestResourceName1 \
--properties
'{
"location": "eastus",
"properties": {
"hello" : "world"
}
}'
Parameter | Required | Description |
---|---|---|
is-full-object | Yes | Indicates whether the properties object includes other options like location, tags, SKU, or plan. |
id | Yes | The resource ID of the custom resource. This ID is an extension of the custom resource provider's resource ID. |
properties | Yes | The request body that will be sent to the endpoint. |
az resource delete --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/myCustomProvider/myCustomResources/myTestResourceName1
Parameter | Required | Description |
---|---|---|
id | Yes | The resource ID of the custom resource. This ID is an extension of the custom resource provider's resource ID. |
az resource show --id /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.CustomProviders/resourceProviders/myCustomProvider/myCustomResources/myTestResourceName1
Parameter | Required | Description |
---|---|---|
id | Yes | The resource ID of the custom resource. This ID is an extension of the custom resource provider's resource ID. |
A sample Resource Manager template:
{
"$schema": "http://schema.management.azure.com/schemas/2019-04-01/deploymentTemplate.json#",
"contentVersion": "1.0.0.0",
"resources": [
{
"type": "Microsoft.CustomProviders/resourceProviders/myCustomResources",
"name": "myCustomProvider/myTestResourceName1",
"apiVersion": "2018-09-01-preview",
"location": "eastus",
"properties": {
"hello": "world"
}
}
]
}
Parameter | Required | Description |
---|---|---|
resourceTypeName | Yes | The name value of the resourceTypes property defined in the custom resource provider. |
resourceProviderName | Yes | The custom resource provider's instance name. |
customResourceName | Yes | The custom resource name. |
Note
After you finish deploying and using the custom resource provider, remember to clean up all created resources including the Azure function app.
In this article, you learned about custom resource providers. For more information, see: