Gateway Api - Create Or Update

服務:

API Management

API 版本:

2021-08-01

將 API 新增至指定的閘道。

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

URI 參數

名稱	位於	必要	類型	Description
apiId	path	True	string	API 識別碼。 目前 API 管理 服務實例中必須是唯一的。
gatewayId	path	True	string	閘道實體標識碼。 目前 API 管理 服務實例中必須是唯一的。 不得有值 'managed'
resourceGroupName	path	True	string	資源群組的名稱。
serviceName	path	True	string	API 管理 服務的名稱。 Regex 模式: ^[a-zA-Z](?:[a-zA-Z0-9-]*[a-zA-Z0-9])?$
subscriptionId	path	True	string	可唯一識別 Microsoft Azure 訂用帳戶的訂用帳戶認證。 訂用帳戶識別碼會構成每個服務呼叫 URI 的一部分。
api-version	query	True	string	要與用戶端要求搭配使用的 API 版本。

要求本文

名稱	類型	Description
properties.provisioningState	ProvisioningState	布建狀態。

回應

名稱	類型	Description
200 OK	ApiContract	指定的 API 已新增至閘道。
201 Created	ApiContract	API 已成功新增至閘道。
Other Status Codes	ErrorResponse	描述作業失敗原因的錯誤回應。

安全性

azure_auth

Azure Active Directory OAuth2 Flow。

類型: oauth2
Flow: implicit
授權 URL: https://login.microsoftonline.com/common/oauth2/authorize

範圍

名稱	Description
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=2021-08-01

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

Java

import com.azure.core.util.Context;
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/2021-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),
                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/2021-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"
)

// Generated from example definition: https://github.com/Azure/azure-rest-api-specs/blob/c767823fdfd9d5e96bad245e3ea4d14d94a716bb/specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-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/2021-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 System;
using System.Threading.Tasks;
using Azure;
using Azure.Core;
using Azure.Identity;
using Azure.ResourceManager;
using Azure.ResourceManager.ApiManagement;
using Azure.ResourceManager.ApiManagement.Models;

// Generated from example definition: specification/apimanagement/resource-manager/Microsoft.ApiManagement/stable/2021-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
  }
}

定義

名稱	Description
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	訂用帳戶金鑰參數名稱詳細數據。

ApiContactInformation

API 連絡資訊

名稱	類型	Description
email	string	連絡人/組織的電子郵件位址。 必須是電子郵件位址的格式
name	string	聯繫人/組織的識別名稱
url	string	指向聯繫人資訊的 URL。 必須是 URL 的格式

ApiContract

API 詳細數據。

名稱	類型	Description
id	string	資源的完整資源識別碼。 例如 - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	資源的名稱
properties.apiRevision	string	描述 API 的修訂。 如果未提供任何值，則會建立預設修訂 1
properties.apiRevisionDescription	string	API 修訂的描述。
properties.apiVersion	string	指出 API 的版本識別碼，如果 API 已建立版本設定
properties.apiVersionDescription	string	API 版本的描述。
properties.apiVersionSet	ApiVersionSetContractDetails	版本設定詳細數據
properties.apiVersionSetId	string	相關 ApiVersionSet 的資源標識碼。
properties.authenticationSettings	AuthenticationSettingsContract	此 API 中包含的驗證設定集合。
properties.contact	ApiContactInformation	API 的連絡資訊。
properties.description	string	API 的描述。 可包含 HTML 格式標籤。
properties.displayName	string	API 名稱。 長度必須為 1 到 300 個字元。
properties.isCurrent	boolean	指出 API 修訂是否為目前的 API 修訂。
properties.isOnline	boolean	指出是否可透過閘道存取 API 修訂。
properties.license	ApiLicenseInformation	API 的授權資訊。
properties.path	string	可在 API 管理服務執行個體內唯一識別此 API 及其所有資源路徑的相對 URL。 此路徑會附加至在服務執行個體建立期間所指定的 API 端點基底 URL，以形成此 API 的公用 URL。
properties.protocols	Protocol[]	描述此 API 中的作業可在哪些通訊協定上叫用。
properties.serviceUrl	string	實作此 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

API 授權資訊

名稱	類型	Description
name	string	用於 API 的授權名稱
url	string	用於 API 之授權的 URL。 必須是 URL 的格式

ApiType

API 的類型。

名稱	類型	Description
graphql	string
http	string
soap	string
websocket	string

ApiVersionSetContractDetails

API 版本集合包含一組與 API 版本相關的常見組態

名稱	類型	Description
description	string	API 版本集的描述。
id	string	現有 API 版本集的識別碼。 省略此值以建立新的版本集。
name	string	API 版本集的顯示名稱。
versionHeaderName	string	如果 versioningScheme 設定 header為 ，表示 API 版本的 HTTP 標頭參數名稱。
versionQueryName	string	如果 versioningScheme 設定 query為 ，則為指出 API 版本的查詢參數名稱。
versioningScheme	enum: Header Query Segment	值，決定 API 版本識別碼在 HTTP 要求中的位置。

AssociationContract

關聯實體詳細數據。

名稱	類型	Description
id	string	資源的完整資源識別碼。 例如 - /subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/{resourceProviderNamespace}/{resourceType}/{resourceName}
name	string	資源的名稱
properties.provisioningState	ProvisioningState	布建狀態。
type	string	資源類型。 例如“Microsoft.Compute/virtualMachines” 或 “Microsoft.Storage/storageAccounts”

AuthenticationSettingsContract

API 驗證設定。

名稱	類型	Description
oAuth2	OAuth2AuthenticationSettingsContract	OAuth2 驗證設定
openid	OpenIdAuthenticationSettingsContract	OpenID Connect 驗證設定

bearerTokenSendingMethods

如何將令牌傳送至伺服器。

名稱	類型	Description
authorizationHeader	string	存取令牌將會使用持有人架構在授權標頭中傳輸
query	string	存取令牌會以查詢參數的形式傳輸。

ErrorFieldContract

錯誤欄位合約。

名稱	類型	Description
code	string	屬性層級錯誤碼。
message	string	人類可讀取的屬性層級錯誤表示法。
target	string	屬性名稱。

ErrorResponse

錯誤回應。

名稱	類型	Description
error.code	string	服務定義的錯誤碼。 此代碼會作為回應中指定之 HTTP 錯誤碼的子狀態。
error.details	ErrorFieldContract[]	在驗證錯誤時，要求中傳送的無效欄位清單。
error.message	string	人類可閱讀的錯誤表示法。

OAuth2AuthenticationSettingsContract

API OAuth2 驗證設定詳細數據。

名稱	類型	Description
authorizationServerId	string	OAuth 授權伺服器識別碼。
scope	string	作業範圍。

OpenIdAuthenticationSettingsContract

API OAuth2 驗證設定詳細數據。

名稱	類型	Description
bearerTokenSendingMethods	bearerTokenSendingMethods[]	如何將令牌傳送至伺服器。
openidProviderId	string	OAuth 授權伺服器識別碼。

Protocol

描述此 API 中的作業可在哪些通訊協定上叫用。

名稱	類型	Description
http	string
https	string
ws	string
wss	string

ProvisioningState

布建狀態。

名稱	類型	Description
created	string

SubscriptionKeyParameterNamesContract

訂用帳戶金鑰參數名稱詳細數據。

名稱	類型	Description
header	string	訂用帳戶金鑰標頭名稱。
query	string	訂用帳戶金鑰查詢字串參數名稱。