Backend - List By Service

Service:

API Management

API Version:

2021-08-01

Lists a collection of backends in the specified service instance.

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/backends?api-version=2021-08-01

With optional parameters:

GET https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/backends?$filter={$filter}&$top={$top}&$skip={$skip}&api-version=2021-08-01

URI Parameters

Name	In	Required	Type	Description
resourceGroupName	path	True	string	The name of the resource group.
serviceName	path	True	string	The name of the API Management service. Regex pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$
subscriptionId	path	True	string	Subscription credentials which uniquely identify Microsoft Azure subscription. The subscription ID forms part of the URI for every service call.
api-version	query	True	string	Version of the API to be used with the client request.
$filter	query		string	| Field | Usage | Supported operators | Supported functions | |-------------|-------------|-------------|-------------| | name | filter | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith | | title | filter | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith | | url | filter | ge, le, eq, ne, gt, lt | substringof, contains, startswith, endswith |
$skip	query		integer int32	Number of records to skip.
$top	query		integer int32	Number of records to return.

Responses

Name	Type	Description
200 OK	BackendCollection	Lists a collection of Backend entities.
Other Status Codes	ErrorResponse	Error response describing why the operation failed.

Security

azure_auth

Azure Active Directory OAuth2 Flow.

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name	Description
user_impersonation	impersonate your user account

Examples

ApiManagementListBackends

Sample request

HTTP

GET https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends?api-version=2021-08-01

Java

import com.azure.core.util.Context;

/** Samples for Backend ListByService. */
public final class Main {
    /*
     * x-ms-original-file: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-08-01/examples/ApiManagementListBackends.json
     */
    /**
     * Sample code: ApiManagementListBackends.
     *
     * @param manager Entry point to ApiManagementManager.
     */
    public static void apiManagementListBackends(com.azure.resourcemanager.apimanagement.ApiManagementManager manager) {
        manager.backends().listByService("rg1", "apimService1", null, null, null, Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Python

from azure.identity import DefaultAzureCredential
from azure.mgmt.apimanagement import ApiManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-apimanagement
# USAGE
    python api_management_list_backends.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = ApiManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="subid",
    )

    response = client.backend.list_by_service(
        resource_group_name="rg1",
        service_name="apimService1",
    )
    for item in response:
        print(item)


# x-ms-original-file: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-08-01/examples/ApiManagementListBackends.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Go

package armapimanagement_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/apimanagement/armapimanagement"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/c767823fdfd9d5e96bad245e3ea4d14d94a716bb/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-08-01/examples/ApiManagementListBackends.json
func ExampleBackendClient_NewListByServicePager() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armapimanagement.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	pager := clientFactory.NewBackendClient().NewListByServicePager("rg1", "apimService1", &armapimanagement.BackendClientListByServiceOptions{Filter: nil,
		Top:  nil,
		Skip: nil,
	})
	for pager.More() {
		page, err := pager.NextPage(ctx)
		if err != nil {
			log.Fatalf("failed to advance page: %v", err)
		}
		for _, v := range page.Value {
			// You could use page here. We use blank identifier for just demo purposes.
			_ = v
		}
		// If the HTTP response code is 200 as defined in example definition, your page structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
		// page.BackendCollection = armapimanagement.BackendCollection{
		// 	Count: to.Ptr[int64](2),
		// 	Value: []*armapimanagement.BackendContract{
		// 		{
		// 			Name: to.Ptr("proxybackend"),
		// 			Type: to.Ptr("Microsoft.ApiManagement/service/backends"),
		// 			ID: to.Ptr("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend"),
		// 			Properties: &armapimanagement.BackendContractProperties{
		// 				Description: to.Ptr("description5308"),
		// 				Credentials: &armapimanagement.BackendCredentialsContract{
		// 					Authorization: &armapimanagement.BackendAuthorizationHeaderCredentials{
		// 						Parameter: to.Ptr("opensesma"),
		// 						Scheme: to.Ptr("Basic"),
		// 					},
		// 					Header: map[string][]*string{
		// 						"x-my-1": []*string{
		// 							to.Ptr("val1"),
		// 							to.Ptr("val2")},
		// 						},
		// 						Query: map[string][]*string{
		// 							"sv": []*string{
		// 								to.Ptr("xx"),
		// 								to.Ptr("bb"),
		// 								to.Ptr("cc")},
		// 							},
		// 						},
		// 						Proxy: &armapimanagement.BackendProxyContract{
		// 							Password: to.Ptr("<password>"),
		// 							URL: to.Ptr("http://192.168.1.1:8080"),
		// 							Username: to.Ptr("Contoso\\admin"),
		// 						},
		// 						TLS: &armapimanagement.BackendTLSProperties{
		// 							ValidateCertificateChain: to.Ptr(false),
		// 							ValidateCertificateName: to.Ptr(false),
		// 						},
		// 						URL: to.Ptr("https://backendname2644/"),
		// 						Protocol: to.Ptr(armapimanagement.BackendProtocolHTTP),
		// 					},
		// 				},
		// 				{
		// 					Name: to.Ptr("sfbackend"),
		// 					Type: to.Ptr("Microsoft.ApiManagement/service/backends"),
		// 					ID: to.Ptr("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sfbackend"),
		// 					Properties: &armapimanagement.BackendContractProperties{
		// 						Description: to.Ptr("Service Fabric Test App 1"),
		// 						Properties: &armapimanagement.BackendProperties{
		// 							ServiceFabricCluster: &armapimanagement.BackendServiceFabricClusterProperties{
		// 								ClientCertificateID: to.Ptr("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/certificates/cert1"),
		// 								ManagementEndpoints: []*string{
		// 									to.Ptr("https://somecluster.com")},
		// 									MaxPartitionResolutionRetries: to.Ptr[int32](5),
		// 									ServerX509Names: []*armapimanagement.X509CertificateName{
		// 										{
		// 											Name: to.Ptr("ServerCommonName1"),
		// 											IssuerCertificateThumbprint: to.Ptr("IssuerCertificateThumbprint1"),
		// 									}},
		// 								},
		// 							},
		// 							URL: to.Ptr("fabric:/mytestapp/mytestservice"),
		// 							Protocol: to.Ptr(armapimanagement.BackendProtocolHTTP),
		// 						},
		// 				}},
		// 			}
	}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { ApiManagementClient } = require("@azure/arm-apimanagement");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to Lists a collection of backends in the specified service instance.
 *
 * @summary Lists a collection of backends in the specified service instance.
 * x-ms-original-file: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-08-01/examples/ApiManagementListBackends.json
 */
async function apiManagementListBackends() {
  const subscriptionId = process.env["APIMANAGEMENT_SUBSCRIPTION_ID"] || "subid";
  const resourceGroupName = process.env["APIMANAGEMENT_RESOURCE_GROUP"] || "rg1";
  const serviceName = "apimService1";
  const credential = new DefaultAzureCredential();
  const client = new ApiManagementClient(credential, subscriptionId);
  const resArray = new Array();
  for await (let item of client.backend.listByService(resourceGroupName, serviceName)) {
    resArray.push(item);
  }
  console.log(resArray);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

dotnet

using System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ApiManagement;
using Azure.ResourceManager.ApiManagement.Models;

// Generated from example definition: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-08-01/examples/ApiManagementListBackends.json
// this example is just showing the usage of "Backend_ListByService" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this ApiManagementServiceResource created on azure
// for more information of creating ApiManagementServiceResource, please refer to the document of ApiManagementServiceResource
string subscriptionId = "subid";
string resourceGroupName = "rg1";
string serviceName = "apimService1";
ResourceIdentifier apiManagementServiceResourceId = ApiManagementServiceResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, serviceName);
ApiManagementServiceResource apiManagementService = client.GetApiManagementServiceResource(apiManagementServiceResourceId);

// get the collection of this ApiManagementBackendResource
ApiManagementBackendCollection collection = apiManagementService.GetApiManagementBackends();

// invoke the operation and iterate over the result
await foreach (ApiManagementBackendResource item in collection.GetAllAsync())
{
    // the variable item is a resource, you could call other operations on this instance as well
    // but just for demo, we get its data from this resource instance
    ApiManagementBackendData resourceData = item.Data;
    // for demo we just print out the id
    Console.WriteLine($"Succeeded on id: {resourceData.Id}");
}

Console.WriteLine($"Succeeded");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Sample response

Status code:

200

{
  "value": [
    {
      "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/proxybackend",
      "type": "Microsoft.ApiManagement/service/backends",
      "name": "proxybackend",
      "properties": {
        "description": "description5308",
        "url": "https://backendname2644/",
        "protocol": "http",
        "credentials": {
          "query": {
            "sv": [
              "xx",
              "bb",
              "cc"
            ]
          },
          "header": {
            "x-my-1": [
              "val1",
              "val2"
            ]
          },
          "authorization": {
            "scheme": "Basic",
            "parameter": "opensesma"
          }
        },
        "proxy": {
          "url": "http://192.168.1.1:8080",
          "username": "Contoso\\admin",
          "password": "<password>"
        },
        "tls": {
          "validateCertificateChain": false,
          "validateCertificateName": false
        }
      }
    },
    {
      "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/backends/sfbackend",
      "type": "Microsoft.ApiManagement/service/backends",
      "name": "sfbackend",
      "properties": {
        "description": "Service Fabric Test App 1",
        "url": "fabric:/mytestapp/mytestservice",
        "protocol": "http",
        "properties": {
          "serviceFabricCluster": {
            "managementEndpoints": [
              "https://somecluster.com"
            ],
            "clientCertificateId": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/certificates/cert1",
            "serverX509Names": [
              {
                "name": "ServerCommonName1",
                "issuerCertificateThumbprint": "IssuerCertificateThumbprint1"
              }
            ],
            "maxPartitionResolutionRetries": 5
          }
        }
      }
    }
  ],
  "count": 2,
  "nextLink": ""
}

Definitions

Name	Description
BackendAuthorizationHeaderCredentials	Authorization header information.
BackendCollection	Paged Backend list representation.
BackendContract	Backend details.
BackendCredentialsContract	Details of the Credentials used to connect to Backend.
BackendProperties	Properties specific to the Backend Type.
BackendProtocol	Backend communication protocol.
BackendProxyContract	Details of the Backend WebProxy Server to use in the Request to Backend.
BackendServiceFabricClusterProperties	Properties of the Service Fabric Type Backend.
BackendTlsProperties	Properties controlling TLS Certificate Validation.
ErrorFieldContract	Error Field contract.
ErrorResponse	Error Response.
X509CertificateName	Properties of server X509Names.

BackendAuthorizationHeaderCredentials

Authorization header information.

Name	Type	Description
parameter	string	Authentication Parameter value.
scheme	string	Authentication Scheme name.

BackendCollection

Paged Backend list representation.

Name	Type	Description
count	integer	Total record count number across all pages.
nextLink	string	Next page link if any.
value	BackendContract[]	Backend values.

BackendContract

Backend details.

Name	Type	Description
id	string	Fully qualified resource ID for the resource. Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	The name of the resource
properties.credentials	BackendCredentialsContract	Backend Credentials Contract Properties
properties.description	string	Backend Description.
properties.properties	BackendProperties	Backend Properties contract
properties.protocol	BackendProtocol	Backend communication protocol.
properties.proxy	BackendProxyContract	Backend Proxy Contract Properties
properties.resourceId	string	Management Uri of the Resource in External System. This url can be the Arm Resource Id of Logic Apps, Function Apps or API Apps.
properties.title	string	Backend Title.
properties.tls	BackendTlsProperties	Backend TLS Properties
properties.url	string	Runtime Url of the Backend.
type	string	The type of the resource. E.g. "Microsoft.Compute/virtualMachines" or "Microsoft.Storage/storageAccounts"

BackendCredentialsContract

Details of the Credentials used to connect to Backend.

Name	Type	Description
authorization	BackendAuthorizationHeaderCredentials	Authorization header authentication
certificate	string[]	List of Client Certificate Thumbprints. Will be ignored if certificatesIds are provided.
certificateIds	string[]	List of Client Certificate Ids.
header	object	Header Parameter description.
query	object	Query Parameter description.

BackendProperties

Properties specific to the Backend Type.

Name	Type	Description
serviceFabricCluster	BackendServiceFabricClusterProperties	Backend Service Fabric Cluster Properties

BackendProtocol

Backend communication protocol.

Name	Type	Description
http	string	The Backend is a RESTful service.
soap	string	The Backend is a SOAP service.

BackendProxyContract

Details of the Backend WebProxy Server to use in the Request to Backend.

Name	Type	Description
password	string	Password to connect to the WebProxy Server
url	string	WebProxy Server AbsoluteUri property which includes the entire URI stored in the Uri instance, including all fragments and query strings.
username	string	Username to connect to the WebProxy server

BackendServiceFabricClusterProperties

Properties of the Service Fabric Type Backend.

Name	Type	Description
clientCertificateId	string	The client certificate id for the management endpoint.
clientCertificatethumbprint	string	The client certificate thumbprint for the management endpoint. Will be ignored if certificatesIds are provided
managementEndpoints	string[]	The cluster management endpoint.
maxPartitionResolutionRetries	integer	Maximum number of retries while attempting resolve the partition.
serverCertificateThumbprints	string[]	Thumbprints of certificates cluster management service uses for tls communication
serverX509Names	X509CertificateName[]	Server X509 Certificate Names Collection

BackendTlsProperties

Properties controlling TLS Certificate Validation.

Name	Type	Default value	Description
validateCertificateChain	boolean	True	Flag indicating whether SSL certificate chain validation should be done when using self-signed certificates for this backend host.
validateCertificateName	boolean	True	Flag indicating whether SSL certificate name validation should be done when using self-signed certificates for this backend host.

ErrorFieldContract

Error Field contract.

Name	Type	Description
code	string	Property level error code.
message	string	Human-readable representation of property-level error.
target	string	Property name.

ErrorResponse

Error Response.

Name	Type	Description
error.code	string	Service-defined error code. This code serves as a sub-status for the HTTP error code specified in the response.
error.details	ErrorFieldContract[]	The list of invalid fields send in request, in case of validation error.
error.message	string	Human-readable representation of the error.

X509CertificateName

Properties of server X509Names.

Name	Type	Description
issuerCertificateThumbprint	string	Thumbprint for the Issuer of the Certificate.
name	string	Common Name of the Certificate.