在 Azure Stack Hub 中将 API 版本配置文件与 Ruby 配合使用

Ruby 与 API 版本配置文件

用于 Azure Stack Hub 资源管理器的 Ruby SDK 提供了相关工具来帮助构建和管理基础结构。 该 SDK 中的资源提供程序包括了采用 Ruby 语言的计算、虚拟网络和存储提供程序。 Ruby SDK 中的 API 配置文件可以用来在公共 Azure 资源和 Azure Stack Hub 上的资源之间进行切换,从而实现混合云开发。

API 配置文件是资源提供程序和服务版本的组合。 可以使用 API 配置文件来组合不同的资源类型。

  • 若要使用所有服务的最新版本,请使用 Azure SDK 汇总 gem 的最新配置文件。
  • 配置文件按日期命名,格式如 V2020_09_01_HybridV2019_03_01_Hybrid
  • 若要使用某个服务的最新 api-version,请使用特定 gem 的最新配置文件。 例如,若要单独使用计算服务的最新 api-version,请使用计算 gem 的最新配置文件。
  • 若要使用某个服务的特定 api-version,请使用在 gem 中定义的特定 API 版本。

安装 Azure Ruby SDK

  • 安装 Git

  • 安装 Ruby

    • 在安装时选择“将 Ruby 添加到 PATH 变量”。

    • 在 Ruby 安装过程中出现提示时,安装开发工具包。

    • 接下来,使用以下命令安装捆绑程序:

      Gem install bundler
      
  • 如果不可用,请创建订阅,并保存订阅 ID 供稍后使用。 有关创建订阅的说明,请参阅在 Azure Stack Hub 中创建套餐的订阅一文。

  • 创建服务主体并保存其 ID 和机密。 有关为 Azure Stack Hub 创建服务主体的说明,请参阅使用应用标识访问资源一文。

  • 确保服务主体在订阅上分配有“参与者/所有者”角色。 有关如何为服务主体分配角色的说明,请参阅使用应用标识访问资源一文。

安装 RubyGem 包

可以直接安装 Azure RubyGem 包。

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

也可以在 Gemfile 中使用这些包。

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

Azure 资源管理器 Ruby SDK 为预览版,在即将推出的版本中可能会有重大界面更改。 在次要版本中,编号数字增加可能表示重大更改。

使用 azure_sdk gem

azure_sdk gem 汇总了 Ruby SDK 中所有受支持的 gem。

可使用以下命令安装 azure_sdk 汇总 gem:

gem install 'azure_sdk'

配置文件

对于包含日期的配置文件,若要使用不同的 SDK 配置文件或版本,请替换中 V<date>_Hybrid 的日期。 例如,对于 2008 版本,配置文件为 2019_03_01,字符串变为 V2019_03_01_Hybrid。 请注意,有时,SDK 团队会更改包的名称,因此仅用不同日期替换字符串的日期可能不起作用。 请参阅下表,了解配置文件与 Azure Stack 版本的关联。

你还可以使用 latest,而不是日期。

Azure Stack 版本 配置文件
2311 2020_09_01
2301 2020_09_01
2206 2020_09_01
2108 2020_09_01
2102 2020_09_01
2008 2019_03_01

有关 Azure Stack Hub 和 API 配置文件的详细信息,请参阅 API 配置文件的摘要

请参阅 Ruby SDK 配置文件

订阅

如果还没有订阅,请创建订阅,并保存稍后要使用的订阅 ID。 有关如何创建订阅的详细信息,请参阅此文档

Service Principal

应创建服务主体及其关联环境信息并将其保存到某个位置。 建议使用具有 owner 角色的服务主体,但根据该示例,contributor 角色即可满足要求。 请参阅下表,查看所需的值。

Value 环境变量 说明
租户 ID AZURE_TENANT_ID Azure Stack Hub 租户 ID
客户端 ID AZURE_CLIENT_ID 在本文上一部分创建服务主体时保存的服务主体应用 ID。
订阅 ID AZURE_SUBSCRIPTION_ID 使用订阅 ID 访问 Azure Stack Hub 中的套餐。
客户端机密 AZURE_CLIENT_SECRET 创建服务主体时保存的服务主体应用机密。
资源管理器终结点 ARM_ENDPOINT 参阅 Azure Stack Hub 资源管理器终结点

租户 ID

若要查找 Azure Stack Hub 的目录或租户 ID,请按照此文中的说明进行操作。

注册资源提供程序

遵循此文档注册所需的资源提供程序。 根据要运行的示例,将需要这些资源提供程序。 例如,如果要运行 VM 示例,则需要 Microsoft.Compute 资源提供程序注册。

Azure Stack 资源管理器终结点

Azure 资源管理器 (ARM) 是一种管理框架,可供管理员用来部署、管理和监视 Azure 资源。 Azure 资源管理器可以通过单个操作以组任务而不是单个任务的形式处理这些任务。 可以从资源管理器终结点获取元数据信息。 该终结点返回 JSON 文件,其中包含运行代码所需的信息。

  • Azure Stack 开发工具包 (ASDK) 中的 ResourceManagerEndpointUrl 是:https://management.local.azurestack.external/
  • 集成系统中的 ResourceManagerEndpointUrl 为 https://management.region.<fqdn>/,其中 <fqdn> 是完全限定的域名。
  • 检索所需的元数据:<ResourceManagerUrl>/metadata/endpoints?api-version=1.0。 有关可用的 API 版本,请参阅 Azure REST API 规范。 例如,在 2020-09-01 配置文件版本中,可以将资源提供程序 microsoft.resourcesapi-version 更改为 2019-10-01

示例 JSON:

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

设置环境变量。

Microsoft Windows

若要设置环境变量,请在 Windows 命令提示符下使用以下格式:

set AZURE_TENANT_ID=<YOUR_TENANT_ID>

基于 macOS、Linux 和 Unix 的系统

在基于 Unix 的系统中,使用以下命令:

export AZURE_TENANT_ID=<YOUR_TENANT_ID>

有关 Azure Stack Hub 和 API 配置文件的详细信息,请参阅 API 配置文件的摘要

Azure Ruby SDK API 配置文件的使用

使用以下代码实例化配置文件客户端。 此参数只是 Azure Stack Hub 或其他私有云所需要的。 默认情况下,公有云 Azure 已经有这些设置。

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)

可以使用配置文件客户端来访问单个资源提供程序,例如计算、存储和网络提供程序:

# 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

定义 Azure Stack Hub 环境设置函数

若要通过 Azure Stack Hub 环境进行服务主体身份验证,请使用 get_active_directory_settings() 来定义终结点 此方法使用之前设置的 ARM_Endpoint 环境变量:

# 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

示例

参考 GitHub 上的以下示例,使用 Ruby 和 Azure Stack Hub API 配置文件来创建解决方案:

示例资源管理器和组

若要运行示例,请确保已安装 Ruby。 如果使用 Visual Studio Code,也请下载 Ruby SDK 扩展。

注意

示例的存储库是 Hybrid-Resource-Manager-Ruby-Resources-And-Groups

  1. 克隆存储库:

    git clone https://github.com/Azure-Samples/Hybrid-Resource-Manager-Ruby-Resources-And-Groups.git
    
  2. 使用捆绑安装依赖项:

    cd Hybrid-Resource-Manager-Ruby-Resources-And-Groups
    bundle install
    
  3. 使用 PowerShell 创建 Azure 服务主体,然后检索所需的值。

    有关如何创建服务主体的说明,请参阅使用 Azure PowerShell 创建具有证书的服务主体

    所需值为:

    • 租户 ID
    • 客户端 ID
    • 客户端机密
    • 订阅 ID
    • 资源管理器终结点

    使用从已创建的服务主体检索的信息设置以下环境变量:

    • 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}

    注意

    在 Windows 上,使用 set 而不是 export

  4. 确保将位置变量设置为你的 Azure Stack Hub 位置,例如 LOCAL="local"

  5. 若要定位正确的活动目录终结点,如果你使用的是 Azure Stack Hub 或其他私有云,请添加以下代码行:

    active_directory_settings = get_active_directory_settings(ENV['ARM_ENDPOINT'])
    
  6. options 变量中添加 Active Directory 设置和适用于 Azure Stack Hub 的基 URL:

    options = {
    credentials: credentials,
    subscription_id: subscription_id,
    active_directory_settings: active_directory_settings,
    base_url: ENV['ARM_ENDPOINT']
    }
    
  7. 创建以 Azure Stack Hub 配置文件为目标的配置文件客户端:

    client = Azure::Resources::Profiles::V2019_03_01_Hybrid::Mgmt::Client.new(options)
    
  8. 若要通过 Azure Stack Hub 进行服务主体身份验证,应使用 get_active_directory_settings() 来定义终结点。 此方法使用之前设置的 ARM_Endpoint 环境变量:

    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. 运行该示例。

    bundle exec ruby example.rb
    

后续步骤