# @azbake/ingredient-apim-api 中文文档

规范地址：https://npmcn.com/package/%40azbake/ingredient-apim-api/

版本：0\.2\.48
npm 元数据更新时间：2026-07-22T19:46:27.830Z
中文译文更新时间：2026-11-07T17:21:43.967Z
软件包许可：MIT

本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。

原始 npm 页面：https://www.npmjs.com/package/%40azbake/ingredient-apim-api
原文对照：https://npmcn.com/package/%40azbake/ingredient-apim-api/?lang=original
项目主页：https://github.com/HomecareHomebase/azure-bake
源码仓库：https://github.com/HomecareHomebase/azure-bake

## 关键信息（来自 npm 元数据）

- 包体积（解压后）：90.4 kB，16 个文件
- 模块格式：CommonJS
- TypeScript 类型：包内自带
- Node.js 要求：\>=16\.4\.2 \<17
- 运行依赖：3 个
- peer 依赖：@azbake/core \*，@azbake/ingredient-utils \*，@azure/ms-rest-nodeauth \*
- 首次发布：2020-06-18T18:05:14.038Z
- 最新版本发布：2026-07-22T19:46:27.638Z
- 近 30 天下载量：3776（2026-10-08 至 2026-11-06，npm 官方下载统计）
- 已发布版本数：48（近 12 个月 2 个）

## 中文简介

用于部署 Azure API 管理实例的材料 .

## 安装

```sh
npm install @azbake/ingredient-apim-api
```

也可以使用：`pnpm add @azbake/ingredient-apim-api`、`yarn add @azbake/ingredient-apim-api`、`bun add @azbake/ingredient-apim-api`

## README

## 更改日志

-   [@azbake/ ingredient- apim- api](https://npmcn.com/package/%40azbake/ingredient-apim-api/CHANGELOG.md)

## 概览

APIM API 成分允许在 Azure APIM 资源内方便地注册和修改 API.

### 成份名称

_@azbake/ ingredient- apim- api_

### 如何纳入食谱

```yaml
name: My package
shortName: mypkg
version: 0.0.1
ingredients:
  - "@azbake/ingredient-apim-api@~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: false #If the recipe only contains an apim api deployment, you don't need to create resource groups
```

### 如何用作成份实例

```yaml
recipe:
  apim-api-deploy:
    properties:
      type: "@azbake/ingredient-apim-api" #ingredient type
      source: "<azure_resource_group_name>/<azure_apim_resource_name>" #identity the azure apim resource to register an API against
      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.
```

## 参数

以下是该成分所有支持的平分仪的文档.

**选项**

```yaml
options:
  apiWaitSeconds: <number>   # Supply a number of seconds to wait for any xml-link/swagger-link urls to become availabile 
                             # before creating the APIM api/policy/etc.
                             # You might be deploying a new API in this recipe, which could take 30-120s to become online.
                             # This setting lets us wait for new APIs to be online
  forceWait: <boolean>       # forces bake to wait the `apiWaitSeconds` value even if the API exists. Useful for allowing a
                             # k8s service deployment to update when using the same version.
  apiRetries: <number>       # number of times the ingredient will retry to add the API
  apiRetryWaitTime: <number> # seconds between retries      
```

**类人鱼**

```yaml
apis: #follows this azure spec for *ApiVersionSetContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3215
  - name: <api-version-name> #unique id for the API (version set) - required
    versions:
      - versionSchema #See next section for version schema
```

**api\[n\].verses (英语)**

```yaml
versions: #follows this azure spec for *ApiCreateOrUpdateParameter* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L180
  - name: <api-name> #typically you want set the id to <api-version-id>-<version> to keep the id consistant for the version set it belongs to - required
    version: <string> #version string that will be used as part of the above ApiVersionSetContract.versioningSchema
    products: #optional list of product names to assign API to
    policies: #see next section for policy schema
    diagnostics: #see next section for diagnostic schema
```

_说明: **ApiCate OrUpdateParemeter.serviceUrl 页面存档备份,存于互联网档案馆 互联网档案馆的存檔,存档日期2013-10-02** 财务报告和审定财务报表 **创建或更新Paremeter 值** 支持定义为 BakeVariables。 这样您就可以将这两个值设定为在部署过程中动态解决端点/数据的表达式_

**api.vers \[n\] (英语). 政策**

```yaml
policies: #scheme follows this azure spec for *PolicyContract* : https://github.com/Azure/azure-sdk-for-js/blob/01898c51c663be4c53e02034a0468cf550ce5279/sdk/apimanagement/arm-apimanagement/src/models/index.ts#L3097
  - operation: <string> #optional, and if not set this will be the default policy set for the entire api. Otherwise, name of an operation within this api to apply the policy to.
```

**api.versions\[n\]. 诊断**

```yaml
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
```

## 工具函数

工具课可以在烘焙内部使用. 参数和源值的 Yaml 文件 .

### `apimapi` 类

| 函数 | 回返 | 说明 |
| --- | --- | --- |
| `get_api(resourceGroup: string, apimName: string, apiId: string)` | `Promise<ApiGetResponse>` | 返回一组参数的 API. |
| `get_backend(resourceGroup: string, apimName: string, backendId: string)` | `Promise<BackendGetResponse>` | 返回一组参数的后端. |
| `get_hostheader(namespace: string, k8sHostname: string, serviceName: string)` | `string` | 返回 API 的主机头 |
| `get_swaggerUrl(namespace: string, k8sHostname: string, version: string, serviceName: string, protocol: string)` | `string` | 返回 API 的 swagger url 页面 |

### 工具函数示例

```yaml
variables:
  api: "[await apimapi.get_api(<apim resource group>, <apim name>, <api id>)]"
  backend: "[await apimapi.get_backend(<apim resource group>, <apim name>, <backend id>)]"
  hostHeader: "[await apimapi.get_hostheader(<api namespace>, <k8sHostName>)]"
  swaggerUrl: "[await apimapi.get_swaggerUrl(<api namespace>, <k8sHostName>), <api version>]"
```

## 样本

```yaml
name: my-api
shortName: myApi
owner: owner
version: 1.0.0
ingredients:
  - "@azbake/ingredient-apim-api@~0"
  - "@azbake/ingredient-app-insights@~0"
resourceGroup: false #no need to create a resource group, just assigning to existing APIM instance
parallelRegions: false
variables:  
  url: http://petstore.swagger.io/v2/swagger.json
  aiName: "[appinsights.get_resource_name('apim-api')]"
  apimName: "[apim.get_resource_name('api')]"
  apimResourceGroup: "[apim.get_resource_group()]"
  # build the source from helper functions
  apimSource: "[apim.get_resource_group() + '/' + apim.get_resource_name('api')]"
recipe:
  my-api-deploy:
    properties:
      type: "@azbake/ingredient-apim-api"
      source: "[coreutils.variable('apimSource')]" #point to existing APIM resource to add API
      condition: "[coreutils.primary_region()]"
      parameters:
        options:
          apiWaitTime: 60 # override to waiting up to 60s for the API to be ready
          forceWait: true # force wait 60s before updating the API in APIM
          apiRetries: 2 # retry adding the API this number of times
          apiRetryWaitTime: 5 # number of seconds between retries
        apis:
          - name: petstore #unique API version identifier across APIM
            displayName: Pet Store API
            description: Pet Store API description
            versioningScheme: Segment
            versions:
              - name: petstore-v1 # unique API identifer across APIM
                version: v1
                apiType: http
                path: pets #base apim url for this api
                protocols: #array of http and/or https
                  - https
                format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
                value: "[coreutils.variable('url')]" #value supports bake variables.
                products:
                  - petstore-product #product should already be created.  if needed you can import APIM ingredient and deploy in the same recipe
                  - starter
                policies: 
                  - 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>{{expressionApiDisplay}}</value>
                                </set-header>
                              </outbound>
                            </policies>
                  - operation: addPet #override the addPet operation policy
                    format: xml
                    value: "<policies> <inbound /> <backend>    </backend>  <outbound /></policies>"
                diagnostics:
                  - name: applicationinsights
                    loggerId: "[(await apim.get_logger(await coreutils.variable('apimResourceGroup'), await coreutils.variable('apimName'), 'aiapim-api')).id]"
                    sampling:
                      samplingType: fixed
                      percentage: 50
              - name: petstore-v2 # unique API identifer across APIM
                version: v2
                apiType: http #unless you're using soap
                path: pets #base apim url for this api
                protocols: #array of http and/or https
                  - https
                format: swagger-link-json #using a swagger link the value needs to be a http based json document to download
                value: "[coreutils.variable('url')]" #value supports bake variables.
                products:
                  - petstore-product
                policies:
                  - 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" />
                              </outbound>
                            </policies>
                  - operation: addPet #override the addPet operation policy
                    format: xml
                    value: "<policies> <inbound /> <backend>    </backend>  <outbound /></policies>"
```

## 常见问题

### @azbake/ingredient-apim-api 是什么？

用于部署 Azure API 管理实例的材料 \.

### 如何安装 @azbake/ingredient-apim-api？

在项目目录运行 npm install @azbake/ingredient-apim-api，或使用 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-api 支持 TypeScript 吗？

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

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

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

### @azbake/ingredient-apim-api 需要什么版本的 Node\.js？

package\.json 的 engines 字段要求 Node\.js \>=16\.4\.2 \<17。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。

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

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

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

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

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

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