Utilize perfis de versão API com .NET no Azure Stack HubUse API version profiles with .NET in Azure Stack Hub

O .NET SDK para o Azure Stack Hub Resource Manager fornece ferramentas para o ajudar a construir e gerir a sua infraestrutura.The .NET SDK for the Azure Stack Hub Resource Manager provides tools to help you build and manage your infrastructure. Os fornecedores de recursos no SDK incluem Compute, Networking, Storage, App Services e Key Vault.Resource providers in the SDK include Compute, Networking, Storage, App Services, and Key Vault. O .NET SDK inclui 14 pacotes NuGet.The .NET SDK includes 14 NuGet packages. Você deve baixar estes pacotes para a sua solução cada vez que compila o seu projeto.You must download these packages to your solution every time you compile your project. No entanto, pode especificamente descarregar qual o fornecedor de recursos que irá utilizar para as versões 2019-03-01-híbridas ou 2018-03-01-híbridas de forma a otimizar a memória para a sua aplicação.However, you can specifically download which resource provider you'll use for the 2019-03-01-hybrid or 2018-03-01-hybrid versions in order to optimize the memory for your app. Cada pacote é composto por um fornecedor de recursos, a respetiva versão API e o perfil API a que pertence.Each package consists of a resource provider, the respective API version, and the API profile to which it belongs. Os perfis da API no .NET SDK permitem o desenvolvimento de nuvem híbrida ajudando-o a alternar entre recursos e recursos globais do Azure Stack Hub.API profiles in the .NET SDK enable hybrid cloud development by helping you switch between global Azure resources and resources on Azure Stack Hub.

Perfis de versão .NET e API.NET and API version profiles

Um perfil API é uma combinação de fornecedores de recursos e versões API.An API profile is a combination of resource providers and API versions. Utilize um perfil API para obter a versão mais recente e estável de cada tipo de recurso num pacote de fornecedor de recursos.Use an API profile to get the latest, most stable version of each resource type in a resource provider package.

  • Para utilizar as versões mais recentes de todos os serviços, utilize o perfil mais recente dos pacotes.To make use of the latest versions of all the services, use the latest profile of the packages. Este perfil faz parte do pacote Microsoft.Azure.Management NuGet.This profile is part of the Microsoft.Azure.Management NuGet package.

  • Para utilizar os serviços compatíveis com o Azure Stack Hub, utilize um dos seguintes pacotes:To use the services compatible with Azure Stack Hub, use one of the following packages:

    • Microsoft.Azure.Management.Profiles.hybrid _ 2019 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkgMicrosoft.Azure.Management.Profiles.hybrid_2019_03_01.<ResourceProvider>.0.9.0-preview.nupkg
    • Microsoft.Azure.Management.Profiles.hybrid _ 2018 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkgMicrosoft.Azure.Management.Profiles.hybrid_2018_03_01.<ResourceProvider>.0.9.0-preview.nupkg

    Certifique-se de que a parte ResourceProvider do pacote NuGet acima é alterada para o fornecedor correto.Ensure that the ResourceProvider portion of the above NuGet package is changed to the correct provider.

  • Para utilizar a versão API mais recente de um serviço, utilize o perfil mais recente do pacote NuGet específico.To use the latest API version of a service, use the Latest profile of the specific NuGet package. Por exemplo, se quiser utilizar a versão mais recente da API apenas do serviço Compute, utilize o perfil mais recente do pacote Compute.For example, if you want to use the latest-API version of the Compute service alone, use the latest profile of the Compute package. O perfil mais recente faz parte do pacote Microsoft.Azure.Management NuGet.The latest profile is part of the Microsoft.Azure.Management NuGet package.

  • Para utilizar versões API específicas para um tipo de recurso num fornecedor de recursos específico, utilize as versões API específicas definidas dentro do pacote.To use specific API versions for a resource type in a specific resource provider, use the specific API versions defined inside the package.

Pode combinar todas as opções na mesma aplicação.You can combine all of the options in the same application.

Instale o Azure .NET SDKInstall the Azure .NET SDK

  • Instale Git.Install Git. Para obter instruções, consulte ["Começar " - Instalar git][].For instructions, see Getting Started - Installing Git.

  • Para instalar as embalagens NuGet corretas, consulte ['Descobrir' e instalar um pacote.][]To install the correct NuGet packages, see Finding and installing a package.

  • As embalagens que precisam de ser instaladas dependem da versão de perfil que pretende utilizar.The packages that need to be installed depend on the profile version you want to use. Os nomes dos pacotes para as versões de perfil são:The package names for the profile versions are:

    • Microsoft.Azure.Management.Profiles.hybrid _ 2019 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkgMicrosoft.Azure.Management.Profiles.hybrid_2019_03_01.<ResourceProvider>.0.9.0-preview.nupkg

    • Microsoft.Azure.Management.Profiles.hybrid _ 2018 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkgMicrosoft.Azure.Management.Profiles.hybrid_2018_03_01.<ResourceProvider>.0.9.0-preview.nupkg

  • Para instalar os pacotes NuGet corretos para Código de Estúdio Visual, consulte o seguinte link para descarregar as instruções do [Gestor de Pacotes NuGet][].To install the correct NuGet packages for Visual Studio Code, see the following link to download the NuGet Package Manager instructions.

  • Se não estiver disponível, crie uma subscrição e guarde o ID de subscrição para ser usado mais tarde.If not available, create a subscription and save the subscription ID to be used later. Para obter informações sobre como criar uma subscrição, consulte Criar subscrições para ofertas no Azure Stack Hub.For information about how to create a subscription, see Create subscriptions to offers in Azure Stack Hub.

  • Crie um diretor de serviço e guarde a identificação do cliente e o segredo do cliente.Create a service principal and save the client ID and the client secret. Para obter informações sobre como criar um principal de serviço para o Azure Stack Hub, consulte [fornecer acesso a aplicações ao Azure Stack Hub][].For information about how to create a service principal for Azure Stack Hub, see Provide applications access to Azure Stack Hub. O ID do cliente também é conhecido como o ID da aplicação ao criar um principal de serviço.The client ID is also known as the application ID when creating a service principal.

  • Certifique-se de que o seu titular de serviço tem a função de contribuinte/proprietário na sua subscrição.Make sure your service principal has the contributor/owner role on your subscription. Para obter informações sobre como atribuir uma função ao principal de serviço, consulte [fornecer acesso às aplicações ao Azure Stack Hub][].For information about how to assign a role to service principal, see Provide applications access to Azure Stack Hub.

Pré-requisitosPrerequisites

Para utilizar o .NET Azure SDK com Azure Stack Hub, deve fornecer os seguintes valores e, em seguida, definir os valores com variáveis ambientais.To use the .NET Azure SDK with Azure Stack Hub, you must supply the following values, and then set the values with environment variables. Para definir as variáveis ambientais, consulte as instruções que seguem a tabela para o seu sistema operativo específico.To set the environmental variables, see the instructions following the table for your specific operating system.

ValorValue Variáveis de ambienteEnvironment variables DescriptionDescription
ID do inquilinoTenant ID AZURE_TENANT_ID O valor do seu [ID][]de inquilino Azure Stack Hub.The value of your Azure Stack Hub tenant ID.
ID de ClienteClient ID AZURE_CLIENT_ID O ID principal da aplicação de serviço salvou quando o diretor de serviço foi criado na secção anterior deste artigo.The service principal app ID saved when the service principal was created in the previous section of this article.
ID da subscriçãoSubscription ID AZURE_SUBSCRIPTION_ID O [ID de subscrição][] é como você acede às ofertas no Azure Stack Hub.The subscription ID is how you access offers in Azure Stack Hub.
Segredo do ClienteClient Secret AZURE_CLIENT_SECRET O segredo da aplicação principal do serviço salvou-se quando o diretor do serviço foi criado.The service principal app secret saved when the service principal was created.
Ponto final do Gestor de RecursosResource Manager Endpoint ARM_ENDPOINT Consulte o ponto final do Azure Stack Hub Resource Manager.See the Azure Stack Hub Resource Manager endpoint.
LocalizaçãoLocation RESOURCE_LOCATION Localização do Azure Stack Hub.Location of Azure Stack Hub.

Para encontrar a identificação do inquilino para o seu Azure Stack Hub, siga as instruções deste artigo.To find the tenant ID for your Azure Stack Hub, follow the instructions in this article. Para definir as variáveis ambientais, faça o seguinte:To set your environment variables, do the following:

WindowsWindows

Para definir as variáveis ambientais numa solicitação de comando do Windows, utilize o seguinte formato:To set the environment variables in a Windows command prompt, use the following format:

set Azure_Tenant_ID=Your_Tenant_ID

Sistemas baseados em MacOS, Linux e UnixMacOS, Linux, and Unix-based systems

Nos sistemas baseados na Unix, utilize o seguinte comando:In Unix-based systems, use the following command:

export Azure_Tenant_ID=Your_Tenant_ID

O ponto final do Gestor de Recursos do Hub Azure StackThe Azure Stack Hub Resource Manager endpoint

O Azure Resource Manager é um quadro de gestão que permite aos administradores implementar, gerir e monitorizar os recursos do Azure.Azure Resource Manager is a management framework that enables administrators to deploy, manage, and monitor Azure resources. O Azure Resource Manager pode lidar com estas tarefas como um grupo, em vez de individualmente, numa única operação.Azure Resource Manager can handle these tasks as a group, rather than individually, in a single operation.

Pode obter a informação de metadados do ponto final do Gestor de Recursos.You can get the metadata info from the Resource Manager endpoint. O ponto final devolve um ficheiro JSON com a informação necessária para executar o seu código.The endpoint returns a JSON file with the info required to run your code.

Note as seguintes considerações:Note the following considerations:

  • O ResourceManagerUrl no Kit de Desenvolvimento da Pilha de Azure (ASDK) é: https://management.local.azurestack.external/ .The ResourceManagerUrl in the Azure Stack Development Kit (ASDK) is: https://management.local.azurestack.external/.

  • O ResourceManagerUrl em sistemas integrados é: https://management.region.<fqdn>/ , onde está o seu nome de domínio totalmente <fqdn> qualificado.The ResourceManagerUrl in integrated systems is: https://management.region.<fqdn>/, where <fqdn> is your fully qualified domain name. Para recuperar os metadados necessários: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0 .To retrieve the metadata required: <ResourceManagerUrl>/metadata/endpoints?api-version=1.0.

Ficheiro JSON da amostra:Sample JSON file:

{
   "galleryEndpoint": "https://portal.local.azurestack.external:30015/",
   "graphEndpoint": "https://graph.windows.net/",
   "portal Endpoint": "https://portal.local.azurestack.external/",
   "authentication": 
      {
         "loginEndpoint": "https://login.windows.net/",
         "audiences": ["https://management.yourtenant.onmicrosoft.com/3cc5febd-e4b7-4a85-a2ed-1d730e2f5928"]
      }
}

Perfis de API existentesExisting API profiles

  • Microsoft.Azure.Management.Profiles.hybrid _ 2019 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkg: Perfil mais recente construído para O Azure Stack Hub.Microsoft.Azure.Management.Profiles.hybrid_2019_03_01.<ResourceProvider>.0.9.0-preview.nupkg: Latest profile built for Azure Stack Hub. Utilize este perfil para que os serviços sejam mais compatíveis com o Azure Stack Hub, desde que esteja na versão 1904 ou posterior.Use this profile for services to be most compatible with Azure Stack Hub, as long as you're on version 1904 or later.

  • Microsoft.Azure.Management.Profiles.hybrid _ 2018 _ 03 _ 01.<ResourceProvider>.0.9.0-preview.nupkg: Utilize este perfil para serviços compatíveis com o Azure Stack Hub para as versões 1808 ou mais tarde.Microsoft.Azure.Management.Profiles.hybrid_2018_03_01.<ResourceProvider>.0.9.0-preview.nupkg: Use this profile for services to be compatible with Azure Stack Hub for versions 1808 or later.

  • Mais recente: Perfil constituído pelas versões mais recentes de todos os serviços.Latest: Profile consisting of the latest versions of all services. Use as versões mais recentes de todos os serviços.Use the latest versions of all the services. Este perfil faz parte do pacote Microsoft.Azure.Management NuGet.This profile is part of the Microsoft.Azure.Management NuGet package.

Para obter mais informações sobre os perfis Azure Stack Hub e API, consulte o [Resumo dos perfis da API.][]For more information about Azure Stack Hub and API profiles, see the Summary of API profiles.

Utilização do perfil Azure .NET SDK APIAzure .NET SDK API profile usage

Utilize o seguinte código para instantaneaizar um cliente de gestão de recursos.Use the following code to instantiate a resource management client. Código semelhante pode ser usado para instantaneaizar outros clientes fornecedores de recursos (como Computação, Rede e Armazenamento).Similar code can be used to instantiate other resource provider clients (such as Compute, Network, and Storage).

var client = new ResourceManagementClient(armEndpoint, credentials)
{
    SubscriptionId = subscriptionId;
};

O credentials parâmetro deste código é necessário para instantaneaizar um cliente.The credentials parameter in this code is required to instantiate a client. O seguinte código gera um sinal de autenticação pelo ID do inquilino e pelo diretor de serviço:The following code generates an authentication token by the tenant ID and the service principal:

var azureStackSettings = getActiveDirectoryServiceSettings(armEndpoint);
var credentials = ApplicationTokenProvider.LoginSilentAsync(tenantId, servicePrincipalId, servicePrincipalSecret, azureStackSettings).GetAwaiter().GetResult();

A getActiveDirectoryServiceSettings chamada no código recupera os pontos finais do Azure Stack Hub a partir do ponto final dos metadados.The getActiveDirectoryServiceSettings call in the code retrieves Azure Stack Hub endpoints from the metadata endpoint. Diz as variáveis ambientais da chamada que é feita:It states the environment variables from the call that's made:

public static ActiveDirectoryServiceSettings getActiveDirectoryServiceSettings(string armEndpoint)
{
    var settings = new ActiveDirectoryServiceSettings();
    try
    {
        var request = (HttpWebRequest)HttpWebRequest.Create(string.Format("{0}/metadata/endpoints?api-version=1.0", armEndpoint));
        request.Method = "GET";
        request.UserAgent = ComponentName;
        request.Accept = "application/xml";
        using (HttpWebResponse response = (HttpWebResponse)request.GetResponse())
        {
            using (StreamReader sr = new StreamReader(response.GetResponseStream()))
            {
                var rawResponse = sr.ReadToEnd();
                var deserialized = JObject.Parse(rawResponse);
                var authenticationObj = deserialized.GetValue("authentication").Value<JObject>();
                var loginEndpoint = authenticationObj.GetValue("loginEndpoint").Value<string>();
                var audiencesObj = authenticationObj.GetValue("audiences").Value<JArray>();
                settings.AuthenticationEndpoint = new Uri(loginEndpoint);
                settings.TokenAudience = new Uri(audiencesObj[0].Value<string>());
                settings.ValidateAuthority = loginEndpoint.TrimEnd('/').EndsWith("/adfs", StringComparison.OrdinalIgnoreCase) ? false : true;
            }
        }
    }
    catch (Exception ex)
    {
        Console.WriteLine(String.Format("Could not get AD service settings. Exception: {0}", ex.Message));
    }
    return settings;
}

Estes passos permitem-lhe utilizar os pacotes NuGet de perfil API para implementar a sua aplicação com sucesso no Azure Stack Hub.These steps enable you to use the API profile NuGet packages to deploy your application successfully to Azure Stack Hub.

Amostras usando perfis de APISamples using API Profiles

Pode utilizar as seguintes amostras como referência para a criação de soluções com perfis API .NET e Azure Stack Hub:You can use the following samples as a reference for creating solutions with .NET and the Azure Stack Hub API profiles:

Passos seguintesNext steps

Saiba mais sobre perfis de API:Learn more about API profiles: