在 Azure Stack Hub 中搭配使用 API 版本設定檔與 Ruby

  • 發行項

Ruby 和 API 版本設定檔

適用於 Azure Stack Hub Resource Manager 的 Ruby SDK 會提供工具，以協助您建置及管理您的基礎結構。 SDK 中的資源提供者包括計算、虛擬網路和具有 Ruby 語言的儲存體。 Ruby SDK 中的 API 設定檔可協助您在全域 Azure 資源和 Azure Stack Hub 的資源之間切換，以提供混合式雲端開發功能。

API 設定檔是資源提供者和服務版本的組合。 您可以使用 API 設定檔來組合不同的資源類型。

  • 若要使用所有服務的最新版本，請使用 Azure SDK 彙總 Gem 的 Latest 設定檔。
  • 設定檔是依日期格式命名，例如 V2020_09_01_Hybrid 或 V2019_03_01_Hybrid。
  • 若要使用服務的最新 api-version，請使用特定 Gem 的 Latest 設定檔。 例如，若要單獨使用計算服務的最新 api-version，請使用 Compute Gem 的 Latest 設定檔。
  • 若要使用服務的特定 api-version，請使用 Gem 內所定義的特定 API 版本。

安裝 Azure Ruby SDK

  • 安裝 Git。

  • 安裝 Ruby。

    • 安裝時，請選擇 [Add Ruby to PATH variable] \(將 Ruby 新增到 PATH 變數\)。

    • 在 Ruby 安裝過程中，於出現提示時安裝開發套件。

    • 接下來，使用下列命令安裝搭配程式：

      Gem install bundler

  • 如果無法使用，請建立訂用帳戶，並儲存訂用帳戶識別碼供後續使用。 如需建立訂用帳戶的指示，請參閱在 Azure Stack Hub 中建立供應項目的訂用帳戶一文。

  • 建立服務主體，並儲存其識別碼和祕密。 如需為 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 Resource Manager Ruby SDK 目前處於預覽狀態，且很可能會在即將發行的版本中推出中斷性的介面變更。 次要版本數字若增加，可能表示有中斷性變更。

使用 azure_sdk Gem

azure_sdk Gem 是 Ruby SDK 中所有已支援 Gem 的彙總。

您可以使用下列命令安裝 azure_sdk 彙總 Gem：

gem install 'azure_sdk'

Profiles

針對包含日期的設定檔，若要使用不同的 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 設定檔。

訂用帳戶

如果您還沒有訂用帳戶，請建立訂用帳戶，並儲存訂用帳戶識別碼以供稍後使用。 如需有關如何建立訂閱的詳細資訊，請參閱此文件。

服務主體

您應建立服務主體及其相關聯的環境資訊，並將其儲存。 建議使用 owner 角色的服務主體，但視範例而定，contributor 角色可能已足夠。 請參閱下表以取得必要的值。

值 環境變數 描述
租用戶識別碼 AZURE_TENANT_ID 您的 Azure Stack Hub 租用戶識別碼。
用戶端識別碼 AZURE_CLIENT_ID 在本文上一節建立服務主體時所儲存的服務主體應用程式識別碼。
訂用帳戶識別碼 AZURE_SUBSCRIPTION_ID 您可使用訂用帳戶識別碼來存取 Azure Stack Hub 中的供應項目。
用戶端密碼 AZURE_CLIENT_SECRET 服務主體建立時儲存的服務主體應用程式祕密。
Resource Manager 端點 ARM_ENDPOINT 請參閱 Azure Stack Hub Resource Manager 端點。

租用戶識別碼

若要尋找 Azure Stack Hub 的目錄或租用戶識別碼，請遵循這篇文章的指示。

註冊資源提供者

遵循此文件來註冊所需的資源提供者。 根據要執行的範例而定會需要這些資源提供者。 例如如果您想要執行 VM 範例，則需要註冊 Microsoft.Compute 資源提供者。

Azure Stack Resource Manager 端點

Azure Resource Manager (ARM) 是可讓系統管理員進行部署、管理及監視 Azure 資源的管理架構。 Azure Resource Manager 能夠以群組方式處理這些工作，而非個別單獨作業的方式。 您可以從 Resource Manager 端點取得中繼資料資訊。 此端點會傳回 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.resources 的 api-version 變更為 2019-10-01。

範例 JSON：

{
   "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"]
      }
}

設定環境變數

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 設定檔建立解決方案的參考：

範例 Resource Manager 與群組

若要執行範例，請確定您已安裝 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. 使用 bundle 安裝相依性：

    cd Hybrid-Resource-Manager-Ruby-Resources-And-Groups
bundle install

  3. 使用 PowerShell 建立 Azure 服務主體，並擷取需要的值。

    如需建立服務主體的指示，請參閱使用 Azure PowerShell 建立具有憑證的服務主體。

    所需的值如下：

    • 租用戶識別碼
    • 用戶端識別碼
    • 用戶端密碼
    • 訂用帳戶識別碼
    • Resource Manager 端點

    使用從您所建立服務主體擷取的資訊，設定下列環境變數：

    • 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. 若要以正確的 Active Directory 端點為目標，如果您使用 Azure Stack Hub 或其他私人雲端，請新增下列程式碼行：

    active_directory_settings = get_active_directory_settings(ENV['ARM_ENDPOINT'])

  6. 在 options 變數中，新增 Active Directory 設定和基底 URL 與 Azure Stack Hub 搭配使用：

    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

後續步驟