Skip to main content

Private Connection (AWS PrivateLink)

Important

To use an AWS PrivateLink connection to the AmiVoice API, you must apply in advance. First, contact us through the Inquiry Form.

After you apply, we configure the connection permission for your AWS account and provide you with the endpoint service name. This section explains the subsequent steps you perform in your VPC, from creating the interface endpoint to our connection approval, enabling private DNS, and verifying the connection.

Overview​

AWS PrivateLink is a service that lets you connect from systems on AWS to external services within the AWS network without exposing the traffic to the internet. There is no need to prepare an internet gateway, NAT Gateway, or public IP address, which simplifies the network configuration. Because the traffic does not go over the internet, you can use it securely without having any path reachable from the outside.

The AmiVoice API is accessed through an interface endpoint that you create in your VPC. Your application can call the AmiVoice API using the same API key as when connecting over the internet.

This feature is not exclusive to AmiVoice API Private. It is also available with the standard edition when the usage conditions are met.

Target Interfaces / APIs and Connection Destinations​

With a PrivateLink connection, you can use the following APIs of the AmiVoice API.

The connection destinations are divided into two: the destination used for Synchronous HTTP / WebSocket and the destination for Asynchronous HTTP.

Interface / API usedConventional host nameHost name for PrivateLink connection
・Synchronous HTTP / WebSocket
・User dictionary operations
・API Key Issuance		acp-api.amivoice.comacp-api-private.amivoice.com
・Asynchronous HTTPacp-api-async.amivoice.comacp-api-async-private.amivoice.com

If you use both Synchronous HTTP / WebSocket and Asynchronous HTTP, create a VPC interface endpoint for each.

Services other than the above, such as MyPage, continue to be used over the internet.

Connection Guide​

1. Prerequisites​

ItemDetails
Regionap-northeast-1 (Tokyo)
Source VPCThe VPC where you create the endpoint
SubnetThe subnet where you place the endpoint (multiple AZs recommended)
Security groupFor the endpoint (allow inbound TCP 443)
VPC DNS settingsEnable DNS resolution and DNS hostnames in advance

If the VPC DNS settings are disabled, the private DNS name described later cannot be resolved.

2. Pre-Registration​

To allow the connection, contact us with the following.

After we configure the permission, we provide an endpoint service name for each interface you use. The name is in the following format.

  • com.amazonaws.vpce.ap-northeast-1.vpce-svc-XXXXXXXXXXXX

If you use both Synchronous and Asynchronous, we provide two service names.

3. Creating the Interface Endpoint​

Perform this procedure for each endpoint service name we provide. If you use both synchronous and asynchronous, you will create two endpoints.

caution

When creating the endpoint, do not enable "Enable private DNS name". Because this service requires manual approval of the connection, if you try to enable private DNS before approval, the creation fails with the following error.

Private DNS can only be enabled after the endpoint connection is accepted by the owner ...

Enable private DNS after 4. Connection Approval (on our side) is complete, using the procedure in 5. Enabling the Private DNS Name.

For the Management Console​

  1. VPC console → Endpoints → Create endpoint
  2. Type: select "Endpoint services that use NLBs and GWLBs"
  3. Enter the service name we provided in Service name and click "Verify service"
    • If it shows "Service name could not be found," the permission setting on our side may not be complete (→ see 2. Pre-Registration)
  4. Select the VPC
  5. Leave "Enable private DNS name" OFF (do not select the checkbox)
  6. Select the AZ and subnet where you place the endpoint
  7. Select the security group (one that allows inbound TCP 443)
  8. Create endpoint

Immediately after creation, the connection status becomes "Pending acceptance".

For the AWS CLI​

aws ec2 create-vpc-endpoint \
  --vpc-endpoint-type Interface \
  --service-name com.amazonaws.vpce.ap-northeast-1.vpce-svc-XXXXXXXXXXXX \
  --vpc-id <CUSTOMER_VPC_ID> \
  --subnet-ids <subnet-id-1> [<subnet-id-2> ...] \
  --security-group-ids <sg-id> \
  --no-private-dns-enabled \
  --region ap-northeast-1 \
  --tag-specifications 'ResourceType=vpc-endpoint,Tags=[{Key=Name,Value=acp-api-private-ep}]'

If you create two endpoints, changing the Name tag for each interface makes them easier to distinguish later.

4. Connection Approval (on our side)​

When you create the endpoint, we receive the connection request on our side. We check the details and approve it. After approval, the endpoint status changes to "Available".

note

Because approval involves a review on our side, it may take some time. Letting us know that the endpoint has been created makes the process smoother.

5. Enabling the Private DNS Name​

After our approval is complete and the endpoint becomes "Available", enable private DNS. This automatically resolves the host name used for the PrivateLink connection to the endpoint you created within your VPC. No additional DNS configuration such as Route 53 is required on your side.

If you created two endpoints, enable it for each.

For the Management Console​

  1. VPC console → Endpoints → select the target endpoint
  2. Actions → Modify private DNS name
  3. Turn "Enable private DNS name for this endpoint" ON → save

For the AWS CLI​

aws ec2 modify-vpc-endpoint \
  --vpc-endpoint-id <vpce-id> \
  --private-dns-enabled \
  --region ap-northeast-1
note
  • This operation can be enabled only when the domain verification on our side is complete
  • The VPC DNS resolution and DNS hostnames must be enabled (1. Prerequisites)

6. Verifying the Connection​

After enabling private DNS, verify from an instance within your VPC. If you created two endpoints, verify each one.

Verifying Name Resolution​

# For Synchronous HTTP and WebSocket
dig +short acp-api-private.amivoice.com

# For Asynchronous HTTP
dig +short acp-api-async-private.amivoice.com

# → If a private IP such as 172.x.x.x is returned, it is OK

Verifying API Connectivity (Speech Recognition)​

Verify using an audio file you have (for example, sample.wav) and an AmiVoice API key. The following is an example of the Synchronous HTTP interface.

curl https://acp-api-private.amivoice.com/v1/recognize \
  -F u={API_KEY} \
  -F d="grammarFileNames=-a-general" \
  -F a=@sample.wav

If the recognition result JSON (such as the text field) is returned, the connection is working correctly.

For the Asynchronous HTTP interface, replace the host name with acp-api-async-private.amivoice.com. For the procedure, please see Asynchronous HTTP Interface.

7. Using It from Your Application​

After verifying the connection, change the AmiVoice API destination host in your application to the host name for the PrivateLink connection. Use acp-api-private.amivoice.com for Synchronous HTTP and WebSocket, and acp-api-async-private.amivoice.com for Asynchronous HTTP. The API path, parameters, and authentication (API key) are the same as before; only the host name changes.

Troubleshooting​

SymptomMain causeAction
The Private DNS can only be enabled after the endpoint connection is accepted ... error on creationYou tried to enable private DNS before approvalCreate with private DNS OFF → enable it after approval using the procedure in 5. Enabling the Private DNS Name
Not found in "Verify service"The permission setting on our side is not completeSend us your AWS account ID
The connection times outThe endpoint security group does not allow 443Add TCP 443 to the SG inbound
The private DNS name cannot be enabledThe domain verification on our side is not complete, or the VPC DNS settings are disabledContact us / enable the VPC DNS resolution and DNS hostnames
The host name for PrivateLink cannot be resolvedThe private DNS name is not enabled, or the VPC DNS settings are disabledEnable private DNS in 5. Enabling the Private DNS Name / check the VPC DNS settings
The status remains "Pending acceptance"Waiting for our approvalContact us
Only Asynchronous HTTP does not connectYou have not created an endpoint for AsynchronousCheck Target Interfaces and Connection Destinations and create an endpoint for Asynchronous as well
TLS certificate errorYou are connecting with something other than the host name (such as specifying the IP directly)Always connect with the host name for PrivateLink

Supplement​

  • The AWS-side VPC endpoint usage fees (hourly charge and data processing charge) are billed to your account based on the AWS pricing structure. If you have prepared a NAT Gateway or similar for internet connectivity, you need to consider that cost together
  • Placing endpoints in multiple AZs improves availability
  • In this configuration, the source IP of the connecting application is not retained on the AmiVoice API side; you are identified by the API key

If you have any questions, please contact our support desk.