Gateway Api - Create Or Update

服务:

API Management

API 版本:

2022-08-01

将 API 添加到指定的网关。

PUT https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.ApiManagement/service/{serviceName}/gateways/{gatewayId}/apis/{apiId}?api-version=2022-08-01

URI 参数

名称	在	必需	类型	说明
apiId	path	True	string minLength: 1 maxLength: 80	API 标识符。 当前 API 管理服务实例中必须是唯一的。
gatewayId	path	True	string minLength: 1 maxLength: 80	网关实体标识符。 当前 API 管理服务实例中必须是唯一的。 不得具有值“managed”
resourceGroupName	path	True	string minLength: 1 maxLength: 90	资源组的名称。 名称不区分大小写。
serviceName	path	True	string minLength: 1 maxLength: 50 pattern: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$	API 管理服务的名称。
subscriptionId	path	True	string minLength: 1	目标订阅的 ID。
api-version	query	True	string minLength: 1	用于此作的 API 版本。

请求正文

名称	类型	说明
properties.provisioningState	ProvisioningState	预配状态。

响应

名称	类型	说明
200 OK	ApiContract	指定的 API 已添加到网关。
201 Created	ApiContract	API 已成功添加到网关。
Other Status Codes	ErrorResponse	描述作失败的原因的错误响应。

安全性

azure_auth

Azure Active Directory OAuth2 Flow。

类型: oauth2
流向: implicit
授权 URL: https://login.microsoftonline.com/common/oauth2/authorize

作用域

名称	说明
user_impersonation	模拟用户帐户

示例

ApiManagementCreateGatewayApi

示例请求

HTTP

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/gateways/gw1/apis/echo-api?api-version=2022-08-01

{
  "properties": {
    "provisioningState": "created"
  }
}

Java

import com.azure.resourcemanager.apimanagement.models.AssociationContract;
import com.azure.resourcemanager.apimanagement.models.ProvisioningState;

/**
 * Samples for GatewayApi CreateOrUpdate.
 */
public final class Main {
    /*
     * x-ms-original-file:
     * specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2022-08-01/examples/
     * ApiManagementCreateGatewayApi.json
     */
    /**
     * Sample code: ApiManagementCreateGatewayApi.
     * 
     * @param manager Entry point to ApiManagementManager.
     */
    public static void
        apiManagementCreateGatewayApi(com.azure.resourcemanager.apimanagement.ApiManagementManager manager) {
        manager.gatewayApis().createOrUpdateWithResponse("rg1", "apimService1", "gw1", "echo-api",
            new AssociationContract().withProvisioningState(ProvisioningState.CREATED),
            com.azure.core.util.Context.NONE);
    }
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Python

from azure.identity import DefaultAzureCredential

from azure.mgmt.apimanagement import ApiManagementClient

"""
# PREREQUISITES
    pip install azure-identity
    pip install azure-mgmt-apimanagement
# USAGE
    python api_management_create_gateway_api.py

    Before run the sample, please set the values of the client ID, tenant ID and client secret
    of the AAD application as environment variables: AZURE_CLIENT_ID, AZURE_TENANT_ID,
    AZURE_CLIENT_SECRET. For more info about how to get the value, please see:
    https://docs.microsoft.com/azure/active-directory/develop/howto-create-service-principal-portal
"""


def main():
    client = ApiManagementClient(
        credential=DefaultAzureCredential(),
        subscription_id="subid",
    )

    response = client.gateway_api.create_or_update(
        resource_group_name="rg1",
        service_name="apimService1",
        gateway_id="gw1",
        api_id="echo-api",
    )
    print(response)


# x-ms-original-file: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2022-08-01/examples/ApiManagementCreateGatewayApi.json
if __name__ == "__main__":
    main()

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

Go

package armapimanagement_test

import (
	"context"
	"log"

	"github.com/Azure/azure-sdk-for-go/sdk/azcore/to"
	"github.com/Azure/azure-sdk-for-go/sdk/azidentity"
	"github.com/Azure/azure-sdk-for-go/sdk/resourcemanager/apimanagement/armapimanagement/v2"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/4cd95123fb961c68740565a1efcaa5e43bd35802/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2022-08-01/examples/ApiManagementCreateGatewayApi.json
func ExampleGatewayAPIClient_CreateOrUpdate() {
	cred, err := azidentity.NewDefaultAzureCredential(nil)
	if err != nil {
		log.Fatalf("failed to obtain a credential: %v", err)
	}
	ctx := context.Background()
	clientFactory, err := armapimanagement.NewClientFactory("<subscription-id>", cred, nil)
	if err != nil {
		log.Fatalf("failed to create client: %v", err)
	}
	res, err := clientFactory.NewGatewayAPIClient().CreateOrUpdate(ctx, "rg1", "apimService1", "gw1", "echo-api", &armapimanagement.GatewayAPIClientCreateOrUpdateOptions{Parameters: &armapimanagement.AssociationContract{
		Properties: &armapimanagement.AssociationContractProperties{
			ProvisioningState: to.Ptr("created"),
		},
	},
	})
	if err != nil {
		log.Fatalf("failed to finish the request: %v", err)
	}
	// You could use response here. We use blank identifier for just demo purposes.
	_ = res
	// If the HTTP response code is 200 as defined in example definition, your response structure would look as follows. Please pay attention that all the values in the output are fake values for just demo purposes.
	// res.APIContract = armapimanagement.APIContract{
	// 	Name: to.Ptr("echo-api"),
	// 	Type: to.Ptr("Microsoft.ApiManagement/service/gateways/apis"),
	// 	ID: to.Ptr("/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/gateways/gw1/apis/echo-api"),
	// 	Properties: &armapimanagement.APIContractProperties{
	// 		APIRevision: to.Ptr("1"),
	// 		IsCurrent: to.Ptr(true),
	// 		SubscriptionKeyParameterNames: &armapimanagement.SubscriptionKeyParameterNamesContract{
	// 			Header: to.Ptr("Ocp-Apim-Subscription-Key"),
	// 			Query: to.Ptr("subscription-key"),
	// 		},
	// 		Path: to.Ptr(""),
	// 		DisplayName: to.Ptr("EchoApi"),
	// 		Protocols: []*armapimanagement.Protocol{
	// 			to.Ptr(armapimanagement.ProtocolHTTP),
	// 			to.Ptr(armapimanagement.ProtocolHTTPS)},
	// 			ServiceURL: to.Ptr("https://contoso.com/apis/echo"),
	// 		},
	// 	}
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

JavaScript

const { ApiManagementClient } = require("@azure/arm-apimanagement");
const { DefaultAzureCredential } = require("@azure/identity");

/**
 * This sample demonstrates how to Adds an API to the specified Gateway.
 *
 * @summary Adds an API to the specified Gateway.
 * x-ms-original-file: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2022-08-01/examples/ApiManagementCreateGatewayApi.json
 */
async function apiManagementCreateGatewayApi() {
  const subscriptionId = process.env["APIMANAGEMENT_SUBSCRIPTION_ID"] || "subid";
  const resourceGroupName = process.env["APIMANAGEMENT_RESOURCE_GROUP"] || "rg1";
  const serviceName = "apimService1";
  const gatewayId = "gw1";
  const apiId = "echo-api";
  const parameters = { provisioningState: "created" };
  const options = { parameters };
  const credential = new DefaultAzureCredential();
  const client = new ApiManagementClient(credential, subscriptionId);
  const result = await client.gatewayApi.createOrUpdate(
    resourceGroupName,
    serviceName,
    gatewayId,
    apiId,
    options
  );
  console.log(result);
}

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

dotnet

using Azure;
using Azure.ResourceManager;
using System;
using System.Threading.Tasks;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager.ApiManagement.Models;
using Azure.ResourceManager.ApiManagement;

// Generated from example definition: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2022-08-01/examples/ApiManagementCreateGatewayApi.json
// this example is just showing the usage of "GatewayApi_CreateOrUpdate" operation, for the dependent resources, they will have to be created separately.

// get your azure access token, for more details of how Azure SDK get your access token, please refer to https://learn.microsoft.com/en-us/dotnet/azure/sdk/authentication?tabs=command-line
TokenCredential cred = new DefaultAzureCredential();
// authenticate your client
ArmClient client = new ArmClient(cred);

// this example assumes you already have this ApiManagementGatewayResource created on azure
// for more information of creating ApiManagementGatewayResource, please refer to the document of ApiManagementGatewayResource
string subscriptionId = "subid";
string resourceGroupName = "rg1";
string serviceName = "apimService1";
string gatewayId = "gw1";
ResourceIdentifier apiManagementGatewayResourceId = ApiManagementGatewayResource.CreateResourceIdentifier(subscriptionId, resourceGroupName, serviceName, gatewayId);
ApiManagementGatewayResource apiManagementGateway = client.GetApiManagementGatewayResource(apiManagementGatewayResourceId);

// invoke the operation
string apiId = "echo-api";
AssociationContract associationContract = new AssociationContract()
{
    ProvisioningState = AssociationEntityProvisioningState.Created,
};
GatewayApiData result = await apiManagementGateway.CreateOrUpdateGatewayApiAsync(apiId, associationContract: associationContract);

Console.WriteLine($"Succeeded: {result}");

To use the Azure SDK library in your project, see this documentation. To provide feedback on this code sample, open a GitHub issue

示例响应

状态代码:

201

{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/gateways/gw1/apis/echo-api",
  "type": "Microsoft.ApiManagement/service/gateways/apis",
  "name": "echo-api",
  "properties": {
    "displayName": "EchoApi",
    "apiRevision": "1",
    "serviceUrl": "https://contoso.com/apis/echo",
    "path": "",
    "protocols": [
      "http",
      "https"
    ],
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "isCurrent": true
  }
}

状态代码:

200

{
  "id": "/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.ApiManagement/service/apimService1/gateways/gw1/apis/echo-api",
  "type": "Microsoft.ApiManagement/service/gateways/apis",
  "name": "echo-api",
  "properties": {
    "displayName": "EchoApi",
    "apiRevision": "1",
    "serviceUrl": "https://contoso.com/apis/echo",
    "path": "",
    "protocols": [
      "http",
      "https"
    ],
    "subscriptionKeyParameterNames": {
      "header": "Ocp-Apim-Subscription-Key",
      "query": "subscription-key"
    },
    "isCurrent": true
  }
}

定义

名称	说明
ApiContactInformation	API 联系信息
ApiContract	API 详细信息。
ApiLicenseInformation	API 许可证信息
ApiType	API 的类型。
ApiVersionSetContractDetails	API 版本集包含一组与 API 版本相关的常见配置
AssociationContract	关联实体详细信息。
AuthenticationSettingsContract	API 身份验证设置。
bearerTokenSendingMethods	如何将令牌发送到服务器。
ErrorFieldContract	错误字段协定。
ErrorResponse	错误响应。
OAuth2AuthenticationSettingsContract	API OAuth2 身份验证设置详细信息。
OpenIdAuthenticationSettingsContract	API OAuth2 身份验证设置详细信息。
Protocol	描述可以调用此 API 中的作的协议。
ProvisioningState	预配状态。
SubscriptionKeyParameterNamesContract	订阅密钥参数名称详细信息。
versioningScheme	一个值，该值确定 API 版本标识符将位于 HTTP 请求中的位置。

ApiContactInformation

Object

API 联系信息

名称	类型	说明
email	string	联系人/组织的电子邮件地址。 必须采用电子邮件地址格式
name	string	联系人/组织的标识名称
url	string	指向联系信息的 URL。 必须采用 URL 格式

ApiContract

Object

API 详细信息。

名称	类型	说明
id	string	资源的完全限定资源 ID。 Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	资源的名称
properties.apiRevision	string minLength: 1 maxLength: 100	描述 API 的修订。 如果未提供任何值，则会创建默认修订版 1
properties.apiRevisionDescription	string maxLength: 256	API 修订的说明。
properties.apiVersion	string maxLength: 100	指示 API 的版本标识符（如果 API 已进行版本控制）
properties.apiVersionDescription	string maxLength: 256	API 版本的说明。
properties.apiVersionSet	ApiVersionSetContractDetails	版本集详细信息
properties.apiVersionSetId	string	相关 ApiVersionSet 的资源标识符。
properties.authenticationSettings	AuthenticationSettingsContract	此 API 中包含的身份验证设置的集合。
properties.contact	ApiContactInformation	API 的联系信息。
properties.description	string	API 的说明。 可能包括 HTML 格式标记。
properties.displayName	string minLength: 1 maxLength: 300	API 名称。 长度必须为 1 到 300 个字符。
properties.isCurrent	boolean	指示 API 修订是否为当前 API 修订版。
properties.isOnline	boolean	指示是否可通过网关访问 API 修订。
properties.license	ApiLicenseInformation	API 的许可证信息。
properties.path	string minLength: 0 maxLength: 400	相对 URL 唯一标识此 API 及其所有资源路径在 API 管理服务实例中。 它追加到服务实例创建期间指定的 API 终结点基 URL，以形成此 API 的公共 URL。
properties.protocols	Protocol[]	描述可以调用此 API 中的作的协议。
properties.serviceUrl	string minLength: 0 maxLength: 2000	实现此 API 的后端服务的绝对 URL。 长度不能超过 2000 个字符。
properties.sourceApiId	string	源 API 的 API 标识符。
properties.subscriptionKeyParameterNames	SubscriptionKeyParameterNamesContract	提供 API 的协议。
properties.subscriptionRequired	boolean	指定访问 API 是否需要 API 或产品订阅。
properties.termsOfServiceUrl	string	API 服务条款的 URL。 必须采用 URL 格式。
properties.type	ApiType	API 的类型。
type	string	资源的类型。 例如“Microsoft.Compute/virtualMachines”或“Microsoft.Storage/storageAccounts”

ApiLicenseInformation

Object

API 许可证信息

名称	类型	说明
name	string	用于 API 的许可证名称
url	string	用于 API 的许可证的 URL。 必须采用 URL 格式

ApiType

枚举

API 的类型。

值	说明
graphql
http
soap
websocket

ApiVersionSetContractDetails

Object

API 版本集包含一组与 API 版本相关的常见配置

名称	类型	说明
description	string	API 版本集的说明。
id	string	现有 API 版本集的标识符。 省略此值以创建新的版本集。
name	string	API 版本集的显示名称。
versionHeaderName	string	如果 versioningScheme 设置为 header，则表示 API 版本的 HTTP 标头参数的名称。
versionQueryName	string	如果 versioningScheme 设置为 query，则指示 API 版本的查询参数的名称。
versioningScheme	versioningScheme	一个值，该值确定 API 版本标识符将位于 HTTP 请求中的位置。

AssociationContract

Object

关联实体详细信息。

名称	类型	说明
id	string	资源的完全限定资源 ID。 Ex - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	资源的名称
properties.provisioningState	ProvisioningState	预配状态。
type	string	资源的类型。 例如“Microsoft.Compute/virtualMachines”或“Microsoft.Storage/storageAccounts”

AuthenticationSettingsContract

Object

API 身份验证设置。

名称	类型	说明
oAuth2	OAuth2AuthenticationSettingsContract	OAuth2 身份验证设置
oAuth2AuthenticationSettings	OAuth2AuthenticationSettingsContract[]	包含在此 API 中的 OAuth2 身份验证设置的集合。
openid	OpenIdAuthenticationSettingsContract	OpenID Connect 身份验证设置
openidAuthenticationSettings	OpenIdAuthenticationSettingsContract[]	此 API 中包含的 Open ID Connect 身份验证设置的集合。

bearerTokenSendingMethods

枚举

如何将令牌发送到服务器。

值	说明
authorizationHeader	使用持有者架构在授权标头中传输访问令牌
query	访问令牌将作为查询参数传输。

ErrorFieldContract

Object

错误字段协定。

名称	类型	说明
code	string	属性级别错误代码。
message	string	属性级错误的人工可读表示形式。
target	string	属性名称。

ErrorResponse

Object

错误响应。

名称	类型	说明
error.code	string	服务定义的错误代码。 此代码充当响应中指定的 HTTP 错误代码的子状态。
error.details	ErrorFieldContract[]	请求中发送的无效字段列表（如果出现验证错误）。
error.message	string	错误的人工可读表示形式。

OAuth2AuthenticationSettingsContract

Object

API OAuth2 身份验证设置详细信息。

名称	类型	说明
authorizationServerId	string	OAuth 授权服务器标识符。
scope	string	作范围。

OpenIdAuthenticationSettingsContract

Object

API OAuth2 身份验证设置详细信息。

名称	类型	说明
bearerTokenSendingMethods	bearerTokenSendingMethods[]	如何将令牌发送到服务器。
openidProviderId	string	OAuth 授权服务器标识符。

Protocol

枚举

描述可以调用此 API 中的作的协议。

值	说明
http
https
ws
wss

ProvisioningState

枚举

预配状态。

值	说明
created

SubscriptionKeyParameterNamesContract

Object

订阅密钥参数名称详细信息。

名称	类型	说明
header	string	订阅密钥标头名称。
query	string	订阅密钥查询字符串参数名称。

versioningScheme

枚举

一个值，该值确定 API 版本标识符将位于 HTTP 请求中的位置。

值	说明
Header	API 版本在 HTTP 标头中传递。
Query	API 版本在查询参数中传递。
Segment	API 版本在路径段中传递。