Use perfis de versão API com Ruby no Azure Stack HubUse API version profiles with Ruby in Azure Stack Hub

Perfis de versão Ruby e APIRuby and API version profiles

O Ruby SDK para o Azure Stack Hub Resource Manager fornece ferramentas para o ajudar a construir e gerir a sua infraestrutura.The Ruby 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, Virtual Networks e Storage, com o idioma Ruby.Resource providers in the SDK include Compute, Virtual Networks, and Storage, with the Ruby language. Os perfis da API no SDK Ruby permitem o desenvolvimento de nuvem híbrida ajudando-o a alternar entre recursos e recursos globais do Azure Stack Hub.API profiles in the Ruby SDK enable hybrid cloud development by helping you switch between global Azure resources and resources on Azure Stack Hub.

Um perfil API é uma combinação de fornecedores de recursos e versões de serviço.An API profile is a combination of resource providers and service versions. Pode utilizar um perfil API para combinar diferentes tipos de recursos.You can use an API profile to combine different resource types.

  • Para utilizar as versões mais recentes de todos os serviços, utilize o perfil mais recente da joia rollup Azure SDK.To use the latest versions of all the services, use the Latest profile of the Azure SDK rollup gem.
  • Para utilizar os serviços compatíveis com o Azure Stack Hub, utilize o perfil de V2019_03_01_Hybrid ou V2018_03_01 da joia rollup Azure SDK.To use the services compatible with the Azure Stack Hub, use the V2019_03_01_Hybrid or V2018_03_01 profile of the Azure SDK rollup gem.
  • Para utilizar a versão api mais recente de um serviço, utilize o perfil mais recente da joia específica.To use the latest api-version of a service, use the Latest profile of the specific gem. Por exemplo, para utilizar a mais recente versão api do serviço de computação, utilize o perfil mais recente da gema Compute.For example, to use the latest api-version of compute service alone, use the Latest profile of the Compute gem.
  • Para utilizar uma versão api específica para um serviço, utilize as versões API específicas definidas dentro da joia.To use a specific api-version for a service, use the specific API versions defined inside the gem.

Nota

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

Instale o Azure Ruby SDKInstall the Azure Ruby SDK

  • Siga as instruções oficiais para instalar o Git.Follow the official instructions to install Git.

  • Siga as instruções oficiais para instalar a Ruby.Follow the official instructions to install Ruby.

    • Ao instalar, escolha adicionar a variável Add Ruby ao PATH.When installing, choose Add Ruby to PATH variable.

    • Quando solicitado durante a instalação ruby, instale o kit de desenvolvimento.When prompted during Ruby installation, install the development kit.

    • Em seguida, instale o pacote utilizando o seguinte comando:Next, install the bundler using the following command:

      Gem install bundler
      
  • 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. As instruções para criar uma subscrição estão nas subscrições do Create para ofertas no artigo do Azure Stack Hub.Instructions to create a subscription are in the Create subscriptions to offers in Azure Stack Hub article.

  • Crie um diretor de serviço e guarde a sua identificação e segredo.Create a service principal and save its ID and secret. Instruções para criar um principal serviço para O Azure Stack Hub estão no Uso de uma identidade de aplicação para aceder a artigo de recursos.Instructions to create a service principal for Azure Stack Hub are in the Use an app identity to access resources article.

  • Certifique-se de que o seu titular de serviço tem a função de contribuinte/proprietário atribuída na sua subscrição.Make sure your service principal has the contributor/owner role assigned on your subscription. Instruções sobre como atribuir uma função a um diretor de serviço estão na Utilização de uma identidade de aplicação para aceder a artigo de recursos.Instructions on how to assign a role to a service principal are in the Use an app identity to access resources article.

Instale os pacotes RubyGemInstall the RubyGem packages

Pode instalar diretamente os pacotes Azure RubyGem.You can install the Azure RubyGem packages directly.

gem install azure_mgmt_compute
gem install azure_mgmt_storage
gem install azure_mgmt_resources
gem install azure_mgmt_network

Ou usa-os na tua Gemfile.Or, use them in your Gemfile.

gem 'azure_mgmt_storage'
gem 'azure_mgmt_compute'
gem 'azure_mgmt_resources'
gem 'azure_mgmt_network'

O Gestor de Recursos Azure Ruby SDK está em pré-visualização e provavelmente terá alterações de interface nas próximas versões.The Azure Resource Manager Ruby SDK is in preview and will likely have breaking interface changes in upcoming releases. Um número aumentado na versão menor pode indicar alterações de rutura.An increased number in the minor version may indicate breaking changes.

Use a joia azure_sdkUse the azure_sdk gem

A joia azure_sdk é um rollup de todas as joias apoiadas no SDK Ruby.The azure_sdk gem is a rollup of all the supported gems in the Ruby SDK. Esta joia é composta por um perfil mais recente, que suporta a versão mais recente de todos os serviços.This gem consists of a Latest profile, which supports the latest version of all services. Inclui perfis V2017_03_09 e V2019_03_01_Hybrid, que são construídos para o Azure Stack Hub.It includes versioned profiles V2017_03_09 and V2019_03_01_Hybrid, which are built for Azure Stack Hub.

Pode instalar a joia rollup azure_sdk com o seguinte comando:You can install the azure_sdk rollup gem with the following command:

gem install 'azure_sdk'

Pré-requisitosPrerequisites

Para utilizar o Ruby Azure SDK com Azure Stack Hub, deve fornecer os seguintes valores e, em seguida, definir os valores com variáveis ambientais.To use the Ruby 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 DescriçãoDescription
ID do inquilinoTenant ID AZURE_TENANT_ID Sua identificação de inquilinoAzure Stack Hub.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 Utiliza o ID de subscrição para aceder a ofertas no Azure Stack Hub.You use the subscription ID to 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.

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

O Microsoft Azure Resource Manager é um quadro de gestão que permite aos administradores implementar, gerir e monitorizar os recursos do Azure.The Microsoft Azure Resource Manager is a management framework that allows admins 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.

Nota

O ResourceManagerUrl no Kit de Desenvolvimento de Pilhas de Azure (ASDK) é: 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 the Azure Stack Development Kit (ASDK) is: https://management.local.azurestack.external/ 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.0To 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"]
  }
}

Definir variáveis de ambienteSet environment variables

Microsoft WindowsMicrosoft Windows

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

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>

Perfis de API existentesExisting API profiles

A Azure_sdk gema rollup tem os seguintes 3 perfis:The Azure_sdk rollup gem has the following 3 profiles:

  • V2019_03_01_Hybrid: Perfil construído para O Azure Stack Hub.V2019_03_01_Hybrid: Profile built for Azure Stack Hub. Utilize este perfil para todas as versões mais recentes de serviços disponíveis na versão 1904 ou posterior do Azure Stack Hub.Use this profile for all the latest versions of services available in Azure Stack Hub version 1904 or later.
  • V2017_03_09: Perfil construído para O Azure Stack Hub.V2017_03_09: Profile built for Azure Stack Hub. Utilize este perfil para que os serviços sejam mais compatíveis com a versão 1808 ou mais cedo do Azure Stack Hub.Use this profile for services to be most compatible with Azure Stack Hub version 1808 or earlier.
  • Mais recente: O perfil consiste nas versões mais recentes de todos os serviços.Latest: Profile consists 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.

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

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

Utilize o seguinte código para instantaneaizar um cliente de perfil.Use the following code to instantiate a profile client. Este parâmetro só é necessário para o Azure Stack Hub ou outras nuvens privadas.This parameter is only required for Azure Stack Hub or other private clouds. A Global Azure já tem estas definições por padrão.Global Azure already has these settings by default.

active_directory_settings = get_active_directory_settings(ENV['ARM_ENDPOINT'])

provider = MsRestAzure::ApplicationTokenProvider.new(
  ENV['AZURE_TENANT_ID'],
  ENV['AZURE_CLIENT_ID'],
  ENV['AZURE_CLIENT_SECRET'],
  active_directory_settings
)
credentials = MsRest::TokenCredentials.new(provider)
options = {
  credentials: credentials,
  subscription_id: subscription_id,
  active_directory_settings: active_directory_settings,
  base_url: ENV['ARM_ENDPOINT']
}

# Target profile built for Azure Stack Hub
client = Azure::Resources::Profiles::V2019_03_01_Hybrid::Mgmt::Client.new(options)

O cliente de perfil pode ser usado para aceder a fornecedores individuais de recursos, tais como Compute, Storage e Network:The profile client can be used to access individual resource providers, such as Compute, Storage, and Network:

# To access the operations associated with Compute
profile_client.compute.virtual_machines.get 'RESOURCE_GROUP_NAME', 'VIRTUAL_MACHINE_NAME'

# Option 1: To access the models associated with Compute
purchase_plan_obj = profile_client.compute.model_classes.purchase_plan.new

# Option 2: To access the models associated with Compute
# Notice Namespace: Azure::Profiles::<Profile Name>::<Service Name>::Mgmt::Models::<Model Name>
purchase_plan_obj = Azure::Profiles::V2019_03_01_Hybrid::Compute::Mgmt::Models::PurchasePlan.new

Defina funções de definição de ambiente do Azure Stack HubDefine Azure Stack Hub environment setting functions

Para autenticar o principal do serviço no ambiente Azure Stack Hub, defina os pontos finais utilizando get_active_directory_settings() .To authenticate the service principal to the Azure Stack Hub environment, define the endpoints using get_active_directory_settings(). Este método utiliza a variável ambiente ARM_Endpoint que definiu anteriormente:This method uses the ARM_Endpoint environment variable that you set previously:

# Get Authentication endpoints using Arm Metadata Endpoints
def get_active_directory_settings(armEndpoint)
  settings = MsRestAzure::ActiveDirectoryServiceSettings.new
  response = Net::HTTP.get_response(URI("#{armEndpoint}/metadata/endpoints?api-version=1.0"))
  status_code = response.code
  response_content = response.body
  unless status_code == "200"
    error_model = JSON.load(response_content)
    fail MsRestAzure::AzureOperationError.new("Getting Azure Stack Hub Metadata Endpoints", response, error_model)
  end
  result = JSON.load(response_content)
  settings.authentication_endpoint = result['authentication']['loginEndpoint'] unless result['authentication']['loginEndpoint'].nil?
  settings.token_audience = result['authentication']['audiences'][0] unless result['authentication']['audiences'][0].nil?
  settings
end

Amostras usando perfis de APISamples using API profiles

Utilize as seguintes amostras no GitHub como referências para criar soluções com perfis API do Hub ruby e Azure Stack:Use the following samples on GitHub as references for creating solutions with Ruby and Azure Stack Hub API profiles:

Gestor de Recursos da Amostra e gruposSample Resource Manager and groups

Para analisar a amostra, certifique-se de que instalou a Ruby.To run the sample, ensure that you've installed Ruby. Se estiver a utilizar o Código do Estúdio Visual, descarregue também a extensão Ruby SDK.If you're using Visual Studio Code, download the Ruby SDK extension as well.

Nota

O repositório para a amostra é Híbrido-Gestor de Recursos-Ruby-Recursos-Recursos-E-Grupos.The repository for the sample is Hybrid-Resource-Manager-Ruby-Resources-And-Groups.

  1. Clone o repositório:Clone the repository:

    git clone https://github.com/Azure-Samples/Hybrid-Resource-Manager-Ruby-Resources-And-Groups.git
    
  2. Instale as dependências utilizando o pacote:Install the dependencies using bundle:

    cd Hybrid-Resource-Manager-Ruby-Resources-And-Groups
    bundle install
    
  3. Crie um principal de serviço Azure utilizando o PowerShell e recupere os valores necessários.Create an Azure service principal using PowerShell and retrieve the values needed.

    Para obter instruções sobre a criação de um principal de serviço, consulte Use Azure PowerShell para criar um principal de serviço com um certificado.For instructions on creating a service principal, see Use Azure PowerShell to create a service principal with a certificate.

    Os valores necessários são:Values needed are:

    • ID do inquilinoTenant ID
    • ID de ClienteClient ID
    • Segredo do clienteClient secret
    • ID da subscriçãoSubscription ID
    • Ponto final do Gestor de RecursosResource Manager endpoint

    Desaprova as seguintes variáveis ambientais utilizando as informações obtidas a partir do principal serviço que criou:Set the following environment variables using the information retrieved from the service principal you created:

    • export AZURE_TENANT_ID={your tenant ID}
    • export AZURE_CLIENT_ID={your client ID}
    • export AZURE_CLIENT_SECRET={your client secret}
    • export AZURE_SUBSCRIPTION_ID={your subscription ID}
    • export ARM_ENDPOINT={your Azure Stack Hub Resource Manager URL}

    Nota

    No Windows, utilize set em vez de export .On Windows, use set instead of export.

  4. Certifique-se de que a variável de localização está definida para a sua localização do Azure Stack Hub; por exemplo, LOCAL="local" . .Ensure the location variable is set to your Azure Stack Hub location; for example, LOCAL="local".

  5. Para direcionar os pontos finais do diretório ativo corretos, adicione a seguinte linha de código se estiver a utilizar o Azure Stack Hub ou outras nuvens privadas:To target the correct active directory endpoints, add the following line of code if you're using Azure Stack Hub or other private clouds:

    active_directory_settings = get_active_directory_settings(ENV['ARM_ENDPOINT'])
    
  6. Na options variável, adicione as definições de Ative Directory e o URL base para trabalhar com o Azure Stack Hub:In the options variable, add the Active Directory settings and the base URL to work with Azure Stack Hub:

    options = {
    credentials: credentials,
    subscription_id: subscription_id,
    active_directory_settings: active_directory_settings,
    base_url: ENV['ARM_ENDPOINT']
    }
    
  7. Crie um cliente de perfil que tenha como alvo o perfil Azure Stack Hub:Create a profile client that targets the Azure Stack Hub profile:

    client = Azure::Resources::Profiles::V2019_03_01_Hybrid::Mgmt::Client.new(options)
    
  8. Para autenticar o principal do serviço com o Azure Stack Hub, os pontos finais devem ser definidos com get_ative_directory_settings().To authenticate the service principal with Azure Stack Hub, the endpoints should be defined using get_active_directory_settings(). Este método utiliza a variável ambiente ARM_Endpoint que definiu anteriormente:This method uses the ARM_Endpoint environment variable that you set previously:

    def get_active_directory_settings(armEndpoint)
      settings = MsRestAzure::ActiveDirectoryServiceSettings.new
      response = Net::HTTP.get_response(URI("#{armEndpoint}/metadata/endpoints?api-version=1.0"))
      status_code = response.code
      response_content = response.body
      unless status_code == "200"
        error_model = JSON.load(response_content)
        fail MsRestAzure::AzureOperationError.new("Getting Azure Stack Hub Metadata Endpoints", response, error_model)
      end
      result = JSON.load(response_content)
      settings.authentication_endpoint = result['authentication']['loginEndpoint'] unless result['authentication']['loginEndpoint'].nil?
      settings.token_audience = result['authentication']['audiences'][0] unless result['authentication']['audiences'][0].nil?
      settings
    end
    
  9. Execute o exemplo.Run the sample.

    bundle exec ruby example.rb
    

Passos seguintesNext steps