@azbake/ingredient-apim

中文文档

0.2.48发布于 2026/07/23MITTypeScriptCommonJS近 30 天下载 3792

Ingredient for deploying and configuring APIs against an APIM instance

文档目录11 节

Changelogs
Overview
Usage
Ingredient Name
How to include in a recipe
How to use as an ingredient instance
Parameters
Utility Functions
apim class
Utility function examples
Sample

Changelogs

@azbake/ingredient-apim

Overview

The APIM ingredient allows for easy standup of a Windows API Management API instance including creation/modification of Products, Subscriptions and more.

Usage

Typical use-case for APIM is to have a single master resource and use secondary regions that sync against the master data. If you are using this use-case you should configure the ingredient instance with a condition of "[coreutils.primary_region()]" so that it only deploys into your primary bake region configuration. Otherwise, the same data will deploy into every apim instance if you have multiple regions.

Ingredient Name

@azbake/ingredient-apim

How to include in a recipe

name: My package
shortName: mypkg
version: 0.0.1
ingredients:
  - "@azbake/ingredient-apim@~0" #include the latest version of the ingredient at build time
parallelRegions: false #typically we only want to deploy to the primary region, so can turn off parallel deploy
resourceGroup: true #Create a resource group for the APIM resource

How to use as an ingredient instance

recipe:
  apim-deploy:
    properties:
      type: "@azbake/ingredient-apim" #ingredient type
      condition: "[coreutils.primary_region()]" #make sure we only execute this against the primary region for multi-region configs
      parameters:
        ... #see documentation below on parameter documentation for how to use.

Parameters

Here is the documentation for all the supported paremeters for this ingredient.

apimService

apimService: #follows this azure spec for *ApiManagementServiceResource* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L4025
  - name: <apim name> #required name of APIM service

diagnostics

diagnostics: #follows this azure spec for *DiagnosticSettingsResource* : https://github.com/Azure/azure-sdk-for-js/blob/20fe312b1122b21811f9364e3d95fe77202e6466/sdk/monitor/arm-monitor/src/models/index.ts#L991
  - name: <diagnostics name> #required name of diagnostics settings

namedValues

namedValues: #follows this azure spec for *NamedValueCreateContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#LL3568C1-L3568C1
  - name: <named value id> #required name of property (named value)

groups

groups: #follows this azure spec for *GroupCreateParameters* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L1882
  - name: <group id> #required name of the group

users

users: #follows this azure spec for *UserCreateParameters* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L2874
  - name: <user id> #required name of the user

subscriptions

subscriptions: #follows this azure spec for *SubscriptionCreateParameters* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L2746
  - name: <subscription id> #required name of the subscription
    user: <user> #optional user lookup, can also use ownerId on SubscriptionCreateParameters if the path is known

apis

#Does not allow for full API buildout (see apim-api ingredient). But allows to delete any api in an APIM instance.
apis:
  - name: <api id> #required name of the api
    delete: boolean # determines whether to delete the API.

products

products: #follows this azure spec for *ProductContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3111
  - name: <product id> #required name of the product
    apis: #optional array of api names to add to product
      - api1
    groups: #optional array of groups to assign to product
      - group1
    policy: #optional policy for prduct.  follows asure spec for *PolicyContract*: https://github.com/Azure/azure-sdk-for-js/blob/20fe312b1122b21811f9364e3d95fe77202e6466/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L797

loggers

loggers: #follows this azure spec for *LoggerContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3537
  - name: <logger name> #required name of the logger
    cleanKeys: true # clean the old subscription keys

authServers

authServers: #follows this azure spec for *AuthorizationServerContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3229
  - name: <auth servier id> #required name of the auth server

identityProviders

identityProviders: #follows this azure spec for *IdentityProviderContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3489
  - identityProviderContractType: microsoft #this is part of the IdentityProviderContract contract and is required

autoScaleSettings

autoScaleSettings: #follows this azure spec for *AutoscaleSettingResource* : https://github.com/Azure/azure-sdk-for-js/blob/20fe312b1122b21811f9364e3d95fe77202e6466/sdk/monitor/arm-monitor/src/models/index.ts#L347
  - name: <auto scale setting name>

backends

backends: #follows this azure spec for *BackendContract*  : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3301
  - name: <back end name>

Utility Functions

Utility classes can be used inside of the bake.yaml file for parameter and source values.

`apim` class

Function	Returns	Description
`get_resource_name(name: string)`	`string`	Gets a standard resource name for an APIM instance
`get_resource_group(name: string = "apim")`	`string`	Gets a standard resource group for an APIM instance
`get_subnet(resourceGroup: string, vnetName: string, subnetName: string)`	`Promise<SubnetsGetResponse>`	Returns the subnet for a given set of parameters.
`get_logger(resourceGroup: string, apimName: string, loggerId: string)`	`Promise<LoggerGetResponse>`	Returns the logger for a given set of parameters.
`get_storageaccount(resourceGroup: string, name: string)`	`Promise<StorageAccountGetPropertiesResponse>`	Returns the storage account for a given set of parameters.
`get_namedValue(resourceGroup: string, apimName: string, namedValueId: string)`	`Promise<PropertyGetResponse>`	Returns the named value (property) for a given set of parameters.
`get_subscription(resourceGroup: string, resource: string, subscriptionId: string)`	`Promise<SubscriptionGetResponse>`	Returns the subscription for a given set of parameters.
`get_subscription_key(resourceGroup: string, resource: string, subscriptionId: string)`	`Promise<string>`	Returns the subscription key for a given set of parameters.
`get_subscription_keySecondary(resourceGroup: string, resource: string, subscriptionId: string)`	`Promise<string>`	Returns the subscription secondary key for a given set of parameters.
`get_source(name: string	null = null)`	`Promise<string>`

Utility function examples

rgOverride: "[apim.get_resource_group()]"
variables:
  apimName: "[apim.get_resource_name(<name>)]"
  subnetResource: "[await apim.get_subnet(<vnet resource Group>, <vnet name>, <subnet name>)]"
  logger: "[await apim.get_logger(<apim resource group>, <apim name>, <logger name>)]"
  storageAccount: "[await apim.get_storageaccount(<storage account resource group>, <storage account name>)]"
  namedValue: "[await apim.get_namedValue(<apim resource group>, <apim name>, <named value id>)]"
  subscription: "[await apim.get_subscription(<apim resource group>, <apim name>, <subscription id>)]"
  subscriptionKey: "[await apim.get_subscription_key(<apim resource group>, <apim name>, <subscription id>)]"
  subscriptionKeySecondary: "[await apim.get_subscription_keySecondary(<apim resource group>, <apim name>, <subscription id>)]"

Sample

name: apim
shortName: apim
owner: arch
version: 1.0.0
ingredients:
  - "@azbake/ingredient-apim@~0"
  - "@azbake/ingredient-app-insights@~0" #use app insights ingredient to create ai resource for diagnostics
resourceGroup: true
parallelRegions: false
rgOverride: "[apim.get_resource_group()]"
variables:
  aiName: "[appinsights.get_resource_name('apim-api')]"
  aiKey: "[await appinsights.get_instrumentation_key('apim-api','appinsights', true)]"
  aiResourceGroup: "[coreutils.resource_group('appinsights', false, null, true)]"
  apimName: "[apim.get_resource_name('api')]"
recipe:
  # deploy app insights first for logger configuration (optional)
  apim-app-insights-deploy: 
    properties:
      type: "@azbake/ingredient-app-insights"
      source: ""
      condition: "[coreutils.current_region_primary()]"
      parameters:
        appInsightsName: "[coreutils.variable('aiName')]"
        rgOverride: "[coreutils.variable('aiResourceGroup')]"
  apim-deploy:
    dependsOn: apim-app-insights-deploy
    properties:      
      type: "@azbake/ingredient-apim"
      condition: "[coreutils.primary_region()]"
      parameters:
        apimService:
          name: "[coreutils.variable('apimName')]"
          location: "[coreutils.current_region().name]"
          publisherEmail: [email protected]
          publisherName: Joe Smith
          sku:
            name: Developer
            capacity: 1
          enableClientCertificate: true
          customProperties:
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls10: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Tls11: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Ciphers.TripleDes168: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Protocols.Ssl30: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls10: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Tls11: "false"
            Microsoft.WindowsAzure.ApiManagement.Gateway.Security.Backend.Protocols.Ssl30: "false"
          virtualNetworkType: External
          virtualNetworkConfiguration:
            subnetResourceId: "[(await apim.get_subnet('RG_VNET_TEST', 'vnettest', 'default')).id]"
        diagnostics:
          name: diag1
          storageAccountId: "[(await apim.get_storageaccount('RG_STORAGE_TEST', 'storagetest')).id]"
          metrics:
            - timeGrain: PT1M
              enabled: true
              retentionPolicy:
                days: 0
                enabled: true
          logs:
            - category: GatewayLogs
              enabled: true
              retentionPolicy:
                days: 0
                enabled: true
        namedValues:
          - name: expression1
            displayName: expression1Display
            value: "@(DateTime.Now.ToString())"
            secret: false
            tags:
              - test
              - test2
        groups:
          - name: "testGroup"
            displayName: "test group"
            description: "test group description"
            type: "custom"
        users:
          - name: john
            email: [email protected]
            firstName: john
            lastName: smith
            groups:
              - testGroup
        apis:
          - name: echo-api #delete the default echo api
            delete: true
        products:
          - name: petstore-product
            displayName: My Petstore
            description: My Petstore Description
            terms: My terms
            subscriptionRequired: false
            state: published
            groups:
              - Administrators
              - Developers
              - testGroup
            policy:
              format: xml #we use a non-link format here to embed the policy, but this could have been xml-link and a http address
              value: <policies>
                        <inbound /> 
                        <backend>    
                          <forward-request /> 
                        </backend>  
                        <outbound>
                          <set-header name="X-Powered-By" exists-action="delete" />
                          <set-header name="X-AspNet-Version" exists-action="delete" />
                          <set-header name="CustomHeader" exists-action="override">
                            <value>{{expression1Display}}</value>
                          </set-header>
                        </outbound>
                      </policies>
        subscriptions:
          - name: petstore-subscription
            user: Administrator
            product: petstore-product
            displayName: petstore-subscription
            state: active
            allowTracing: true
        loggers:
          - name: apimLogger
            cleanKeys: true
            description: apimlogger
            loggerType: applicationInsights
            credentials: 
              instrumentationKey: "[coreutils.variable('aiKey')]"
        authServers:
          - name: auth
            displayName: authDisplay
            description: auth description
            clientRegistrationEndpoint: "<endpoint>"
            authorizationEndpoint: "<endpoint>"
            tokenEndpoint: "<endpoint>"
            clientId: clientid
            clientSecret: clientSecret
            clientAuthenticationMethod:
              - Body
            authorizationMethods:
              - GET
            grantTypes:
              - implicit
        identityProviders:
          - identityProviderContractType: microsoft
            clientId : clientid
            clientSecret: clientSecret
        autoScaleSettings:
              - name: apim-autoscale
                enabled: true
                profiles:
                  - name: default
                    capacity:
                      minimum: "1"
                      maximum: "2"
                      default: "1"
                    rules: 
                      - metricTrigger: 
                          metricName: Capacity
                          timeGrain: PT1M
                          statistic: Average
                          timeWindow: PT10M
                          timeAggregation: Average
                          operator: GreaterThan
                          threshold: 80
                        scaleAction:
                          direction: Increase
                          type: ChangeCount
                          value: "1"
                          cooldown: PT60M
                      - metricTrigger: 
                          metricName: Capacity
                          timeGrain: PT1M
                          statistic: Average
                          timeWindow: PT10M
                          timeAggregation: Average
                          operator: LessThan
                          threshold: 35
                        scaleAction:
                          direction: Decrease
                          type: ChangeCount
                          value: "1"
                          cooldown: PT90M
                notifications:
                  - email:
                      sendToSubscriptionAdministrator: true
                      sendToSubscriptionCoAdministrators: true

版本与发布记录

@azbake/ingredient-apim 共发布 78 个版本，首次发布于 2019/11/09；过去 12 个月发布了 2 个版本。

版本	发布日期	距今
`0.2.48`latest	2026/07/23	3 个月前
`0.2.47`	2026/07/21	3 个月前
`0.2.46`	2024/07/25	2 年前
`0.2.45`	2023/05/25	3 年前
`0.2.44`	2023/05/25	3 年前
`0.2.43`	2023/03/22	3 年前

关于 @azbake/ingredient-apim 的常见问题

@azbake/ingredient-apim 是什么？

Ingredient for deploying and configuring APIs against an APIM instance

如何安装 @azbake/ingredient-apim？

在项目目录运行 npm install @azbake/ingredient-apim，或使用 pnpm add / yarn add / bun add。它还需要宿主项目提供 peer 依赖：@azbake/core（*）、@azbake/ingredient-utils（*）、@azure/ms-rest-nodeauth（*）。npm 7 及以上与 pnpm 8 及以上默认会自动安装必需的 peer 依赖，Yarn 需要手动安装。

@azbake/ingredient-apim 支持 TypeScript 吗？

支持。包内自带 TypeScript 类型声明（package.json 声明了 types 入口），安装后即可获得类型提示，无需再安装 @types 包。

@azbake/ingredient-apim 支持 ESM 还是 CommonJS？

以 CommonJS 形式发布，可以直接 require()；在 ES Module 项目中也可以用 import 引入（Node.js 会把 module.exports 作为默认导出）。

@azbake/ingredient-apim 可以商用吗？

@azbake/ingredient-apim 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。

@azbake/ingredient-apim 的下载量有多少？

根据 npm 官方下载统计，@azbake/ingredient-apim 在 2026/10/08 – 2026/11/06 这 30 天内被下载 3,792 次，日均约 126 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。

@azbake/ingredient-apim 还在维护吗？

最新版本 0.2.48 发布于 2026/07/23（3 个月前）；至今共发布 78 个版本，其中过去 12 个月发布了 2 个；首次发布于 2019/11/09。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。

npm install @azbake/ingredient-apim

pnpmpnpm add @azbake/ingredient-apim
yarnyarn add @azbake/ingredient-apim
bunbun add @azbake/ingredient-apim

peer 依赖@azbake/core *@azbake/ingredient-utils *@azure/ms-rest-nodeauth *

npm 7+ 与 pnpm 8+ 会自动安装必需的 peer 依赖，Yarn 需手动安装。

在你的项目目录中运行此命令。

近 30 天下载

3,792

约 3792 次日均 126 次

统计周期 2026/10/08 – 2026/11/06
数据来自 npm 官方下载统计，今天更新

最新版本0.2.48发布于 3 个月前

开源许可MIT宽松许可

包体积137 kB15 个文件 · 解压后

运行依赖5 个另有 3 个 peer 依赖

模块格式CommonJS

TypeScript自带类型

发布版本78 个近 12 个月 2 个

首次发布2019/11/096 年前

元数据更新2026/07/23

每一个软件包背后，
都有分享与创造的人。