Compute
Elastic Cloud Server
Huawei Cloud Flexus
Bare Metal Server
Auto Scaling
Image Management Service
Dedicated Host
FunctionGraph
Cloud Phone Host
Huawei Cloud EulerOS
Networking
Virtual Private Cloud
Elastic IP
Elastic Load Balance
NAT Gateway
Direct Connect
Virtual Private Network
VPC Endpoint
Cloud Connect
Enterprise Router
Enterprise Switch
Global Accelerator
Management & Governance
Cloud Eye
Identity and Access Management
Cloud Trace Service
Resource Formation Service
Tag Management Service
Log Tank Service
Config
OneAccess
Resource Access Manager
Simple Message Notification
Application Performance Management
Application Operations Management
Organizations
Optimization Advisor
IAM Identity Center
Cloud Operations Center
Resource Governance Center
Migration
Server Migration Service
Object Storage Migration Service
Cloud Data Migration
Migration Center
Cloud Ecosystem
KooGallery
Partner Center
User Support
My Account
Billing Center
Cost Center
Resource Center
Enterprise Management
Service Tickets
HUAWEI CLOUD (International) FAQs
ICP Filing
Support Plans
My Credentials
Customer Operation Capabilities
Partner Support Plans
Professional Services
Analytics
MapReduce Service
Data Lake Insight
CloudTable Service
Cloud Search Service
Data Lake Visualization
Data Ingestion Service
GaussDB(DWS)
DataArts Studio
Data Lake Factory
DataArts Lake Formation
IoT
IoT Device Access
Others
Product Pricing Details
System Permissions
Console Quick Start
Common FAQs
Instructions for Associating with a HUAWEI CLOUD Partner
Message Center
Security & Compliance
Security Technologies and Applications
Web Application Firewall
Host Security Service
Cloud Firewall
SecMaster
Anti-DDoS Service
Data Encryption Workshop
Database Security Service
Cloud Bastion Host
Data Security Center
Cloud Certificate Manager
Edge Security
Managed Threat Detection
Blockchain
Blockchain Service
Web3 Node Engine Service
Media Services
Media Processing Center
Video On Demand
Live
SparkRTC
MetaStudio
Storage
Object Storage Service
Elastic Volume Service
Cloud Backup and Recovery
Storage Disaster Recovery Service
Scalable File Service Turbo
Scalable File Service
Volume Backup Service
Cloud Server Backup Service
Data Express Service
Dedicated Distributed Storage Service
Containers
Cloud Container Engine
SoftWare Repository for Container
Application Service Mesh
Ubiquitous Cloud Native Service
Cloud Container Instance
Databases
Relational Database Service
Document Database Service
Data Admin Service
Data Replication Service
GeminiDB
GaussDB
Distributed Database Middleware
Database and Application Migration UGO
TaurusDB
Middleware
Distributed Cache Service
API Gateway
Distributed Message Service for Kafka
Distributed Message Service for RabbitMQ
Distributed Message Service for RocketMQ
Cloud Service Engine
Multi-Site High Availability Service
EventGrid
Dedicated Cloud
Dedicated Computing Cluster
Business Applications
Workspace
ROMA Connect
Message & SMS
Domain Name Service
Edge Data Center Management
Meeting
AI
Face Recognition Service
Graph Engine Service
Content Moderation
Image Recognition
Optical Character Recognition
ModelArts
ImageSearch
Conversational Bot Service
Speech Interaction Service
Huawei HiLens
Video Intelligent Analysis Service
Developer Tools
SDK Developer Guide
API Request Signing Guide
Terraform
Koo Command Line Interface
Content Delivery & Edge Computing
Content Delivery Network
Intelligent EdgeFabric
CloudPond
Intelligent EdgeCloud
Solutions
SAP Cloud
High Performance Computing
Developer Services
ServiceStage
CodeArts
CodeArts PerfTest
CodeArts Req
CodeArts Pipeline
CodeArts Build
CodeArts Deploy
CodeArts Artifact
CodeArts TestPlan
CodeArts Check
CodeArts Repo
Cloud Application Engine
MacroVerse aPaaS
KooMessage
KooPhone
KooDrive

Creating a gRPC API

Updated on 2025-01-24 GMT+08:00

APIG supports gRPC API creation. gRPC is a modern, open-source, high-performance Remote Procedure Call (RPC) framework that can run in any environment. You only need to define the request and response of each API, and let the gRPC framework take care of the rest. gRPC uses protocol buffers (protobuf) as its Interface Definition Language (IDL) and for bottom-layer message exchange. The following table compares gRPC and REST APIs.

Table 1 Differences between gRPC and REST APIs

Parameter

gRPC

REST

Message encoding

protobuf

JSON

Transmission protocol

HTTP/2

HTTP

Transmission performance

Fast, with less content to transmit

More content to transmit

Transmission mode

  • Unary RPC

    Send a single request and receive a single response.

  • Server streaming RPC

    Send a single request and receive multiple responses.

  • Client streaming RPC

    Send multiple requests and receive a single response.

  • Bidirectional streaming RPC

    Send multiple requests and receive multiple responses.

Send a single request and receive a single response.

If both your client and server are of the gRPC type, you can create an gRPC API to open up your backend capabilities. gRPC features low resource consumption and high transmission rate. It is suitable for internal service invocation and governance.

Constraints

  • gRPC APIs cannot be imported, exported, or debugged, and do not support the import of API design files, CSE microservices, or CCE workloads.
  • Circuit breaker policies whose backend policy type is Mock, HTTP&HTTPS, or FunctionGraph are not supported.
  • Base64 encoding is not supported.
  • Parameter orchestration is not supported.

Prerequisites

  • You have created an API group. If no API group is available, create one by referring to Creating an API Group.
  • If the backend service needs to use a load balance channel, create a channel first.
  • The backend service has a proto file that defines API request and response parameters. The proto file is used in gRPC to define data structures and service APIs. It describes data structures and interactions using protobuf and serves as a contract for communication between the client and backend services.

Creating a gRPC API

  1. Go to the APIG console.
  2. Select a gateway at the top of the navigation pane.
  1. In the navigation pane, choose API Management > API Groups.
  2. Click a group name to go to the Group Information page.
  3. On the APIs tab page, choose Create API > Create gRPC API.

    1. Configure the frontend parameters described in the following table.
      The new API must have a different group, request method, request path, and matching mode from those of any existing API.
      Table 2 Frontend definition

      Parameter

      Description

      API Name

      Enter an API name that conforms to specific rules to facilitate search.

      Enter 3 to 255 characters, starting with a letter or digit. Use only letters, digits, and these special characters: -_./:()

      Group

      The group to which the API belongs. To create a group, click Create API Group.

      URL

      Frontend address, which consists of a method, protocol, subdomain name, and path.

      • Method: defaults to POST.
      • Protocol: defaults to GRPCS.
      • Subdomain Name: Debugging domain name of the group to which the API belongs.
      • Path: Set the path to any of the following:
        • /
        • /{Package name}.{Service name}
        • /{Package name}.{Service name}/{Method name}
        NOTE:
        • Obtain the package name, service name, and method name from the proto file.
        • Absolute match can be used only when the frontend path is set to /{Package name}.{Service name}/{Method name}.

      Gateway Response

      Displayed if an API request fails to be processed.

      APIG provides a set of default responses and also allows you to create new ones with custom status codes and content on the Group Information page. The response content must be in JSON format.

      Matching

      Matching mode of the API request path.

      • Exact match: The path in a request for the API must be the same as the value of Path.
      • Prefix match: The path in a request for the API must be prefixed with the value of Path. You can define multiple paths in this mode.

        For example, if you set Path to /test/AA and Matching to Prefix match, the API can be called using /test/AA/BB and /test/AA/CC but cannot be called using /test/AACC.

      NOTE:
      • If you set the matching mode to Prefix match, the characters of the API request path excluding the prefix are transparently transmitted to the backend.

        For example, if you define the frontend and backend request paths of an API as /test/ and /test2/, respectively, and the API is called using /test/AA/CC, the characters AA/CC will be transparently transmitted to the backend. The request URL received by the backend is /test2/AA/CC/.

      • In prefix match mode, the path in a request preferentially matches the API with the longest path.

        For example, assume that prefix match is enabled for two APIs whose paths are /test/AA and /test/AA/BB, respectively. The path /test/AA/BB/c in a request matches the API whose path is /test/AA/BB.

      • If there are two APIs with the same group, request method, and request path, the API with exact matching is first called.

      Tags

      Attributes used to quickly identify the API from other APIs.

      The value can contain 1 to 128 characters, including letters, digits, and the following special characters: _-*#%.:. It must start with a letter. Separate multiple tags with commas (,).

      Description

      API description, which contains 1 to 1,000 characters.

      Request Body Content

      Enter the content of the request body in the API request to help API callers understand how to correctly encapsulate API requests.

    2. Configure security settings based on the following table.
      Table 3 Security configuration

      Parameter

      Description

      Type

      Determine whether the API is available to the public. Options:

      • Public: The API can be released to KooGallery.
      • Private: The API will be excluded when the API group to which it belongs is released on KooGallery.

      Authentication Mode

      The following authentication modes are available:

      • App: Requests will be authenticated by APIG. This authentication mode is recommended.
      • IAM: Requests will be authenticated by IAM.
      • Custom: Requests for the API will be authenticated by using your own authentication system or service (for example, an OAuth-based authentication system).
      • None: No authentication will be required. To call APIs that do not require authentication, construct standard HTTP requests and send them to APIG.

        APIG transparently transmits requests to call an API that does not require authentication to the backend service. If you want requests to be authenticated on the API backend service, you can set Security Authentication to None. The API caller transfers the fields required for authentication to the backend service, and the backend service performs authentication.

      API calling varies depending on the authentication mode. For details, see Calling an Open API.

      NOTICE:
      • If you set the authentication mode of an API to IAM, any APIG user can access the API, which can result in excessive charges if the API is bombarded with malicious requests.
      • If you set the authentication mode of an API to None, any user can access the API over public networks, which can result in excessive charges if the API is bombarded with malicious requests.
      • If you set the authentication mode to Custom, you can create a function in FunctionGraph to interconnect with your own authentication system or service. Ensure that FunctionGraph is available in the current region.

      Simple Authentication

      This parameter is available only if you set Security Authentication to App.

      If you select app authentication, configure whether to enable simple authentication. In simple authentication, the X-Apig-AppCode parameter is added to the gRPCS request header for quick response. APIG verifies only the AppCode and the request content does not need to be signed.

      Simple authentication only supports gRPCS requests and does not support gRPC requests. For details, see Configuring AppCodes for Simple Authentication.

      NOTE:

      After you enable simple authentication for an existing API, you need to publish the API again. For details, see Publishing an API.

      Two-Factor Authentication

      This parameter is available only if Authentication Mode is set to App or IAM.

      This parameter specifies whether to perform two-way authentication on API calling. If this parameter is selected, the custom function API is also used to authenticate API requests when APP or IAM has been selected for Security Authentication.

      Custom Authorizer

      This parameter is mandatory only if Authentication Mode is set to Custom.

      Select a frontend custom authorizer you have created. If no custom authorizer is available, click Create Custom Authorizer on the right to create a frontend custom authorizer.

      CORS

      Determine whether to enable cross-origin resource sharing (CORS).

      CORS allows browsers to send XMLHttpRequest to servers in other domains, overcoming the limitation that Asynchronous JavaScript and XML (AJAX) can be used only within the same domain.

      There are two types of CORS requests:

      • Simple requests: requests that have the Origin field in the header.
      • Not-so-simple requests: gRPC requests sent before the actual request.

      If CORS (not-so-simple request) is enabled for an API, another API that uses the OPTIONS method must be created. For details, see Enabling CORS.

  4. Click Next and configure the backend service.
  5. Define the default backend.

    API requests that do not meet the conditions of any backend will be forwarded to the default backend.

    On the Backend Configuration page, select a backend type.

    Backend types include Table 4 and Table 5.

    NOTE:

    FunctionGraph backends can be set only if FunctionGraph has been deployed in the current environment.

    gRPC APIs with a FunctionGraph backend are supported in CN Southwest-Guiyang1, CN East-Shanghai1, CN North-Beijing4, CN East-Shanghai2, and LA-Santiago.

    Table 4 Parameters for defining a gRPC&gRPCS backend service

    Parameter

    Description

    Load Balance Channel

    Determine whether to use a load balance channel to access backend services.

    URL

    A URL consists of a method, protocol, load balance channel/backend address, and path.

    • Method

      The default value is POST.

    • Protocol

      GRPC or GRPCS. This protocol must be the one used by the backend service.

    • Load Balance Channel

      Set this parameter only if a load balance channel is used. Select an existing load balance channel or create one.

      To ensure a successful health check and service availability, configure the security groups of cloud servers in each channel to allow access from 100.125.0.0/16.

    • Backend Address

      Set this parameter if no load balance channel is used.

      Enter the access address of the backend service in the format of Host:Port. Host indicates the IP address or domain name for accessing the backend service. Port is the port of the backend service. If no port is specified, port 80 is used for gRPC by default, and port 443 is used for gRPCS by default.

      To use environment variables in the backend address, enclose the variables with number signs (#), for example, #ipaddress#. You can use multiple environment variables, for example, #ipaddress##test#.

      NOTE:

      If you have enabled public outbound access for a gateway, the IP address or domain name can be a public IP address (ECS EIP, public IP address of your own server, or ELB address), a public domain name, or a private network IP address. Private domain names cannot be used.

      Gateways created after October 30, 2022 can transmit server name indication (SNI) to backend services during TLS handshake.

    • Path

      The request path (URI) of the backend service. Ensure that any parameters in the path are enclosed in braces ({}). For example, /getUserInfo/{userId}.

      If the path contains an environment variable, enclose the environment variable in number signs (#), for example, /#path#. You can use multiple environment variables, for example, /#path##request#.

    NOTE:
    • APIs whose URLs contain variables cannot be debugged on the API debugging page.
    • For variables defined in URLs of APIs, corresponding environment variables and their values must be configured. Otherwise, the APIs cannot be published because there will be no values that can be assigned to the variables.
    • The variable name is case-sensitive.

    Host Header

    Set this parameter only if a load balance channel is used.

    Host header field in the backend service request. By default, the original host header in each request is used.

    Timeout (ms)

    Backend request timeout. Range: 1–60,000 ms.

    • If a backend timeout error occurs during API debugging, increase the timeout to locate the reason.
    • If the current timeout does not meet your service requirements, modify the maximum timeout by referring to Configuring Gateway Parameters. The value range is 1 ms to 600,000 ms. After modifying the maximum timeout, also modify the timeout here.

    Retries

    Number of attempts to retry requesting the backend service. Default: 0; range: –1 to 10.

    • If the value is –1, the retry function is disabled. However, requests except for those using POST and PATCH will be retried once by default.
    • If the value is within 0 to 10, the retry function is enabled, and requests will retry for the specified number of times. 0 indicates no retry attempts will be made.

    If a load balance channel is used, the number of retries must be less than the number of enabled backend servers in the channel.

    Two-Way Authentication

    Set this parameter only when Protocol is set to GRPCS.

    Determine whether to enable two-way authentication between APIG and the backend service. If you enable this option, configure the backend_client_certificate parameter when Configuring Gateway Parameters.

    Backend Authentication

    Determine whether your backend service needs to authenticate API requests.

    If you enable this option, select a custom authorizer for backend authentication. Custom authorizers are functions that are created in FunctionGraph to implement an authentication logic or to invoke an authentication service.

    NOTE:

    Backend authentication relies on FunctionGraph and is only available in certain regions.

    Table 5 Parameters for defining a FunctionGraph backend service

    Parameter

    Description

    Function Name

    Automatically displayed when you select a function.

    Function URN

    Identifier of the function.

    Click Select to specify a function.

    Version/Alias

    Select a version or alias for your function. For details, see Version Management or Alias Management.

    Invocation Mode

    Default: Synchronous. When receiving an invocation request, FunctionGraph immediately processes the request and returns a result. The client closes the connection once it has received a response from the backend.

    Timeout (ms)

    Backend request timeout. Range: 1–60,000 ms.

    • If a backend timeout error occurs during API debugging, increase the timeout to locate the reason.
    • If the current timeout does not meet your service requirements, modify the maximum timeout by referring to Configuring Gateway Parameters. The value range is 1 ms to 600,000 ms. After modifying the maximum timeout, also modify the timeout here.

    Backend Authentication

    Determine whether your backend service needs to authenticate API requests.

    If you enable this option, select a custom authorizer for backend authentication. Custom authorizers are functions that are created in FunctionGraph to implement an authentication logic or to invoke an authentication service.

    NOTE:

    Backend authentication relies on FunctionGraph and is only available in certain regions.

  6. (Optional) Add a backend policy.

    You can add backend policies to forward requests to different backend services.

    1. Click to add a backend policy.
    2. Set policy parameters described in Table 6. For details about other parameters, see Table 4 and Table 5.
      Table 6 Backend policy parameters

      Parameter

      Description

      Name

      The backend policy name.

      Start with a letter, and use letters, digits, hyphens (-), and underscores (_). (3 to 64 characters)

      Effective Mode

      Select the effective mode of the backend policy.

      • Any condition met: The backend policy takes effect if any of the policy conditions has been met.
      • All conditions met: The backend policy takes effect only when all the policy conditions have been met.

      Policy Conditions

      Conditions that must be met for the backend policy to take effect. Set conditions by referring to Table 7.

      Table 7 Policy Conditions

      Parameter

      Description

      Source

      Source of the conditions specified in the policy

      • Source IP address: IP address from which the API is called
      • Request parameter: a request parameter defined for the API
      • Cookie: cookies of an API request
      • System parameter: a default gateway parameter used to define system runtime for the API
      NOTICE:
      • The request parameters (for example, headers) set as policy conditions must have already been defined for the API.
      • If System parameter is not displayed, contact technical support to upgrade the gateway.

      Parameter Name

      • When setting Source to Request parameter, select a request parameter.
      • When setting Source to System parameter, select a system parameter.
        • reqPath: Request URI, for example, /a/b/c.
        • reqMethod: Request method, for example, GET.
      • When setting Source to Cookie, enter the name of a cookie parameter.

      Parameter Location

      The parameter location is displayed only if you set Source to Request parameter.

      Condition Type

      This parameter is mandatory only if you set Source to Request parameter, Cookie, or System parameter.

      • Equal: The request parameter must be equal to the specified value.
      • Enumerated: The request parameter must be equal to any of the enumerated values.
      • Matching: The request parameter must be equal to any value of the regular expression.
      NOTE:

      When you set Source to System parameter and select a parameter named reqMethod, you can set the condition type only to Equal or Enumerated.

      Condition Value

      Enter the condition value. The value contains 1 to 1,024 characters.

      • If Condition Type is Equal, enter a value.
      • If Condition Type is Enumerated, enter multiple values and separate them with commas (,).
      • If Condition Type is Matching, enter a value range, for example, [0-5].
      • If Source is Source IP address, enter one or more IP addresses and separate them with commas (,).
      • If Source is System parameter - Frontend authentication parameter and the condition value is of the Boolean type, the parameter must be in lowercase.

  7. Click Finish. You can view the API details on the APIs tab that is displayed.

Related Documents

Routing gRPC Service Requests

We use cookies to improve our site and your experience. By continuing to browse our site you accept our cookie policy. Find out more

Feedback

Feedback

Feedback

0/500

Selected Content

Submit selected content with the feedback