Documentation
¶
Overview ¶
Package endpoints provides the types and functionality for defining regions and endpoints, as well as querying those definitions.
The SDK's Regions and Endpoints metadata is code generated into the endpoints package, and is accessible via the DefaultResolver function. This function returns a endpoint Resolver will search the metadata and build an associated endpoint if one is found. The default resolver will search all partitions known by the SDK. e.g AWS Standard (aws), AWS China (aws-cn), and AWS GovCloud (US) (aws-us-gov). .
Enumerating Regions and Endpoint Metadata ¶
Casting the Resolver returned by DefaultResolver to a EnumPartitions interface will allow you to get access to the list of underlying Partitions with the Partitions method. This is helpful if you want to limit the SDK's endpoint resolving to a single partition, or enumerate regions, services, and endpoints in the partition.
resolver := endpoints.NewDefaultResolver()
partitions := resolver.Partitions()
for _, p := range partitions {
fmt.Println("Regions for", p.ID())
for id, _ := range p.Regions() {
fmt.Println("*", id)
}
fmt.Println("Services for", p.ID())
for id, _ := range p.Services() {
fmt.Println("*", id)
}
}
Using Custom Endpoints ¶
The endpoints package also gives you the ability to use your own logic how endpoints are resolved. This is a great way to define a custom endpoint for select services, without passing that logic down through your code.
If a type implements the Resolver interface it can be used to resolve endpoints. To use this with the SDK's Session and Config set the value of the type to the EndpointsResolver field of aws.Config when initializing the service client.
In addition the ResolverFunc is a wrapper for a func matching the signature of Resolver.ResolveEndpoint, converting it to a type that satisfies the Resolver interface.
defaultResolver := endpoints.NewDefaultResolver()
myCustomResolver := func(service, region string) (aws.Endpoint, error) {
if service == endpoints.S3ServiceID {
return aws.Endpoint{
URL: "s3.custom.endpoint.com",
SigningRegion: "custom-signing-region",
}, nil
}
return defaultResolver.ResolveEndpoint(service, region)
}
cfg, err := external.LoadDefaultAWSConfig()
if err != nil {
panic(err)
}
cfg.Region = "us-west-2"
cfg.EndpointResolver = aws.EndpointResolverFunc(myCustomResolver)
Index ¶
- Constants
- type DecodeModelOptions
- type Endpoint
- type Partition
- func (p Partition) Endpoint(service, region string, opts ResolveOptions) (aws.Endpoint, error)
- func (p Partition) ID() string
- func (p Partition) Regions() map[string]Region
- func (p Partition) RegionsForService(id string) (map[string]Region, bool)
- func (p Partition) Resolver() *Resolver
- func (p Partition) Services() map[string]Service
- type Partitions
- type Region
- type ResolveOptions
- type Resolver
- type Service
- type UnknownEndpointError
- type UnknownServiceError
Examples ¶
Constants ¶
const ( AwsPartitionID = "aws" // AWS Standard partition. AwsCnPartitionID = "aws-cn" // AWS China partition. AwsUsGovPartitionID = "aws-us-gov" // AWS GovCloud (US) partition. )
Partition identifiers
const ( ApNortheast1RegionID = "ap-northeast-1" // Asia Pacific (Tokyo). ApNortheast2RegionID = "ap-northeast-2" // Asia Pacific (Seoul). ApSouth1RegionID = "ap-south-1" // Asia Pacific (Mumbai). ApSoutheast1RegionID = "ap-southeast-1" // Asia Pacific (Singapore). ApSoutheast2RegionID = "ap-southeast-2" // Asia Pacific (Sydney). CaCentral1RegionID = "ca-central-1" // Canada (Central). EuCentral1RegionID = "eu-central-1" // EU (Frankfurt). EuWest1RegionID = "eu-west-1" // EU (Ireland). EuWest2RegionID = "eu-west-2" // EU (London). EuWest3RegionID = "eu-west-3" // EU (Paris). SaEast1RegionID = "sa-east-1" // South America (Sao Paulo). UsEast1RegionID = "us-east-1" // US East (N. Virginia). UsEast2RegionID = "us-east-2" // US East (Ohio). UsWest1RegionID = "us-west-1" // US West (N. California). UsWest2RegionID = "us-west-2" // US West (Oregon). )
AWS Standard partition's regions.
const ( CnNorth1RegionID = "cn-north-1" // China (Beijing). CnNorthwest1RegionID = "cn-northwest-1" // China (Ningxia). )
AWS China partition's regions.
const ( AcmServiceID = "acm" // Acm. ApiPricingServiceID = "api.pricing" // ApiPricing. ApigatewayServiceID = "apigateway" // Apigateway. ApplicationAutoscalingServiceID = "application-autoscaling" // ApplicationAutoscaling. Appstream2ServiceID = "appstream2" // Appstream2. AthenaServiceID = "athena" // Athena. AutoscalingServiceID = "autoscaling" // Autoscaling. AutoscalingPlansServiceID = "autoscaling-plans" // AutoscalingPlans. BatchServiceID = "batch" // Batch. BudgetsServiceID = "budgets" // Budgets. ClouddirectoryServiceID = "clouddirectory" // Clouddirectory. CloudformationServiceID = "cloudformation" // Cloudformation. CloudfrontServiceID = "cloudfront" // Cloudfront. CloudhsmServiceID = "cloudhsm" // Cloudhsm. Cloudhsmv2ServiceID = "cloudhsmv2" // Cloudhsmv2. CloudsearchServiceID = "cloudsearch" // Cloudsearch. CloudsearchdomainServiceID = "cloudsearchdomain" // Cloudsearchdomain. CloudtrailServiceID = "cloudtrail" // Cloudtrail. CodebuildServiceID = "codebuild" // Codebuild. CodecommitServiceID = "codecommit" // Codecommit. CodedeployServiceID = "codedeploy" // Codedeploy. CodepipelineServiceID = "codepipeline" // Codepipeline. CodestarServiceID = "codestar" // Codestar. CognitoIdentityServiceID = "cognito-identity" // CognitoIdentity. CognitoIdpServiceID = "cognito-idp" // CognitoIdp. CognitoSyncServiceID = "cognito-sync" // CognitoSync. ConfigServiceID = "config" // Config. CurServiceID = "cur" // Cur. DataIotServiceID = "data.iot" // DataIot. DatapipelineServiceID = "datapipeline" // Datapipeline. DaxServiceID = "dax" // Dax. DevicefarmServiceID = "devicefarm" // Devicefarm. DirectconnectServiceID = "directconnect" // Directconnect. DiscoveryServiceID = "discovery" // Discovery. DmsServiceID = "dms" // Dms. DsServiceID = "ds" // Ds. DynamodbServiceID = "dynamodb" // Dynamodb. Ec2ServiceID = "ec2" // Ec2. Ec2metadataServiceID = "ec2metadata" // Ec2metadata. EcrServiceID = "ecr" // Ecr. EcsServiceID = "ecs" // Ecs. ElasticacheServiceID = "elasticache" // Elasticache. ElasticbeanstalkServiceID = "elasticbeanstalk" // Elasticbeanstalk. ElasticfilesystemServiceID = "elasticfilesystem" // Elasticfilesystem. ElasticloadbalancingServiceID = "elasticloadbalancing" // Elasticloadbalancing. ElasticmapreduceServiceID = "elasticmapreduce" // Elasticmapreduce. ElastictranscoderServiceID = "elastictranscoder" // Elastictranscoder. EmailServiceID = "email" // Email. EntitlementMarketplaceServiceID = "entitlement.marketplace" // EntitlementMarketplace. EsServiceID = "es" // Es. EventsServiceID = "events" // Events. FirehoseServiceID = "firehose" // Firehose. GameliftServiceID = "gamelift" // Gamelift. GlacierServiceID = "glacier" // Glacier. GlueServiceID = "glue" // Glue. GreengrassServiceID = "greengrass" // Greengrass. HealthServiceID = "health" // Health. IamServiceID = "iam" // Iam. ImportexportServiceID = "importexport" // Importexport. InspectorServiceID = "inspector" // Inspector. IotServiceID = "iot" // Iot. KinesisServiceID = "kinesis" // Kinesis. KinesisanalyticsServiceID = "kinesisanalytics" // Kinesisanalytics. KinesisvideoServiceID = "kinesisvideo" // Kinesisvideo. KmsServiceID = "kms" // Kms. LambdaServiceID = "lambda" // Lambda. LightsailServiceID = "lightsail" // Lightsail. LogsServiceID = "logs" // Logs. MachinelearningServiceID = "machinelearning" // Machinelearning. MarketplacecommerceanalyticsServiceID = "marketplacecommerceanalytics" // Marketplacecommerceanalytics. MediaconvertServiceID = "mediaconvert" // Mediaconvert. MedialiveServiceID = "medialive" // Medialive. MediapackageServiceID = "mediapackage" // Mediapackage. MeteringMarketplaceServiceID = "metering.marketplace" // MeteringMarketplace. MghServiceID = "mgh" // Mgh. MobileanalyticsServiceID = "mobileanalytics" // Mobileanalytics. ModelsLexServiceID = "models.lex" // ModelsLex. MonitoringServiceID = "monitoring" // Monitoring. MturkRequesterServiceID = "mturk-requester" // MturkRequester. OpsworksServiceID = "opsworks" // Opsworks. OpsworksCmServiceID = "opsworks-cm" // OpsworksCm. OrganizationsServiceID = "organizations" // Organizations. PinpointServiceID = "pinpoint" // Pinpoint. PollyServiceID = "polly" // Polly. RdsServiceID = "rds" // Rds. RedshiftServiceID = "redshift" // Redshift. RekognitionServiceID = "rekognition" // Rekognition. Route53ServiceID = "route53" // Route53. Route53domainsServiceID = "route53domains" // Route53domains. RuntimeLexServiceID = "runtime.lex" // RuntimeLex. S3ServiceID = "s3" // S3. SdbServiceID = "sdb" // Sdb. ServicecatalogServiceID = "servicecatalog" // Servicecatalog. ServicediscoveryServiceID = "servicediscovery" // Servicediscovery. ShieldServiceID = "shield" // Shield. SmsServiceID = "sms" // Sms. SnowballServiceID = "snowball" // Snowball. SnsServiceID = "sns" // Sns. SqsServiceID = "sqs" // Sqs. SsmServiceID = "ssm" // Ssm. StatesServiceID = "states" // States. StoragegatewayServiceID = "storagegateway" // Storagegateway. StreamsDynamodbServiceID = "streams.dynamodb" // StreamsDynamodb. StsServiceID = "sts" // Sts. SupportServiceID = "support" // Support. SwfServiceID = "swf" // Swf. TaggingServiceID = "tagging" // Tagging. WafServiceID = "waf" // Waf. WafRegionalServiceID = "waf-regional" // WafRegional. WorkdocsServiceID = "workdocs" // Workdocs. WorkspacesServiceID = "workspaces" // Workspaces. XrayServiceID = "xray" // Xray. )
Service identifiers
const (
UsGovWest1RegionID = "us-gov-west-1" // AWS GovCloud (US).
)
AWS GovCloud (US) partition's regions.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type DecodeModelOptions ¶
type DecodeModelOptions struct {
SkipCustomizations bool
}
A DecodeModelOptions are the options for how the endpoints model definition are decoded.
func (*DecodeModelOptions) Set ¶
func (d *DecodeModelOptions) Set(optFns ...func(*DecodeModelOptions))
Set combines all of the option functions together.
type Endpoint ¶
type Endpoint struct {
// contains filtered or unexported fields
}
A Endpoint provides information about endpoints, and provides the ability to resolve that endpoint for the service, and the region the endpoint represents.
type Partition ¶
type Partition struct {
// contains filtered or unexported fields
}
A Partition provides the ability to enumerate the partition's regions and services.
func AwsCnPartition ¶
func AwsCnPartition() Partition
AwsCnPartition returns the Resolver for AWS China.
func AwsPartition ¶
func AwsPartition() Partition
AwsPartition returns the Resolver for AWS Standard.
func AwsUsGovPartition ¶
func AwsUsGovPartition() Partition
AwsUsGovPartition returns the Resolver for AWS GovCloud (US).
func (Partition) Endpoint ¶
Endpoint attempts to resolve the endpoint based on service and region. See Options for information on configuring how the endpoint is resolved.
If the service cannot be found in the metadata the endpoint will be resolved based on the parition's endpoint pattern, and service endpoint prefix.
When resolving endpoints you can choose to enable StrictMatching. This will require the provided service and region to be known by the partition. If the endpoint cannot be strictly resolved an error will be returned. This mode is useful to ensure the endpoint resolved is valid. Without StrictMatching enabled the endpoint returned my look valid but may not work. StrictMatching requires the SDK to be updated if you want to take advantage of new regions and services expansions.
Errors that can be returned.
- UnknownServiceError
- UnknownEndpointError
func (Partition) Regions ¶
Regions returns a map of Regions indexed by their ID. This is useful for enumerating over the regions in a partition.
func (Partition) RegionsForService ¶
RegionsForService returns the map of regions for the service id specified. false is returned if the service is not found in the partition.
type Partitions ¶
type Partitions []Partition
Partitions is a slice of paritions describing regions and endpoints
func DefaultPartitions ¶
func DefaultPartitions() Partitions
DefaultPartitions returns a list of the partitions the SDK is bundled with. The available partitions are: AWS Standard, AWS China, and AWS GovCloud (US).
partitions := endpoints.DefaultPartitions
for _, p := range partitions {
// ... inspect partitions
}
func (Partitions) ForPartition ¶
func (ps Partitions) ForPartition(id string) (Partition, bool)
ForPartition returns the parition with the matching ID passed in.
func (Partitions) ForRegion ¶
func (ps Partitions) ForRegion(id string) (Partition, bool)
ForRegion returns the first partition which includes the region passed in. This includes both known regions and regions which match a pattern supported by the partition which may include regions that are not explicitly known by the partition. Use the Regions method of the returned Partition if explicit support is needed.
type Region ¶
type Region struct {
// contains filtered or unexported fields
}
A Region provides information about a region, and ability to resolve an endpoint from the context of a region, given a service.
type ResolveOptions ¶
type ResolveOptions struct {
// DisableSSL forces the endpoint to be resolved as HTTP.
// instead of HTTPS if the service supports it.
DisableSSL bool
// Sets the resolver to resolve the endpoint as a dualstack endpoint
// for the service. If dualstack support for a service is not known and
// StrictMatching is not enabled a dualstack endpoint for the service will
// be returned. This endpoint may not be valid. If StrictMatching is
// enabled only services that are known to support dualstack will return
// dualstack endpoints.
UseDualStack bool
// Enables strict matching of services and regions resolved endpoints.
// If the partition doesn't enumerate the exact service and region an
// error will be returned. This option will prevent returning endpoints
// that look valid, but may not resolve to any real endpoint.
StrictMatching bool
}
ResolveOptions provide the configuration needed to direct how the endpoints will be resolved.
type Resolver ¶
type Resolver struct {
ResolveOptions
// contains filtered or unexported fields
}
A Resolver provides endpoint resolution based on modeled endpoint data.
func DecodeModel ¶
func DecodeModel(r io.Reader, optFns ...func(*DecodeModelOptions)) (*Resolver, error)
DecodeModel unmarshals a Regions and Endpoint model definition file into a endpoint Resolver. If the file format is not supported, or an error occurs when unmarshaling the model an error will be returned.
Casting the return value of this func to a EnumPartitions will allow you to get a list of the partitions in the order the endpoints will be resolved in.
resolver, err := endpoints.DecodeModel(reader)
partitions := resolver.Partitions()
for _, p := range partitions {
// ... inspect partitions
}
func NewDefaultResolver ¶
func NewDefaultResolver() *Resolver
NewDefaultResolver returns an Endpoint resolver that will be able to resolve endpoints for: AWS Standard, AWS China, and AWS GovCloud (US).
Use DefaultPartitions() to get the list of the default partitions.
func (*Resolver) Partitions ¶
func (r *Resolver) Partitions() Partitions
Partitions returns the partitions that make up the resolver.
Example ¶
package main
import (
"fmt"
"github.com/aws/aws-sdk-go-v2/aws/endpoints"
)
func main() {
partitions := endpoints.NewDefaultResolver().Partitions()
for _, p := range partitions {
fmt.Println("Regions for", p.ID())
for id := range p.Regions() {
fmt.Println("*", id)
}
fmt.Println("Services for", p.ID())
for id := range p.Services() {
fmt.Println("*", id)
}
}
}
Output:
func (*Resolver) ResolveEndpoint ¶
ResolveEndpoint attempts to resolve an endpoint againsted the modeled endpoint data. If an endpoint is found it will be returned. An error will be returned otherwise.
Searches through the partitions in the order they are defined.
type Service ¶
type Service struct {
// contains filtered or unexported fields
}
A Service provides information about a service, and ability to resolve an endpoint from the context of a service, given a region.
func (Service) Endpoint ¶
Endpoint resolves an endpoint from the context of a service given a region. See Partition.EndpointFor for usage and errors that can be returned.
type UnknownEndpointError ¶
type UnknownEndpointError struct {
Partition string
Service string
Region string
Known []string
// contains filtered or unexported fields
}
A UnknownEndpointError is returned when in StrictMatching mode and the service is valid, but the region does not resolve to an endpoint. Includes a list of all known endpoints for the service.
func NewUnknownEndpointError ¶
func NewUnknownEndpointError(p, s, r string, known []string) UnknownEndpointError
NewUnknownEndpointError builds and returns UnknownEndpointError.
func (UnknownEndpointError) Error ¶
func (e UnknownEndpointError) Error() string
String returns the string representation of the error.
func (UnknownEndpointError) String ¶
func (e UnknownEndpointError) String() string
String returns the string representation of the error.
type UnknownServiceError ¶
type UnknownServiceError struct {
Partition string
Service string
Known []string
// contains filtered or unexported fields
}
A UnknownServiceError is returned when the service does not resolve to an endpoint. Includes a list of all known services for the partition. Returned when a partition does not support the service.
func NewUnknownServiceError ¶
func NewUnknownServiceError(p, s string, known []string) UnknownServiceError
NewUnknownServiceError builds and returns UnknownServiceError.
func (UnknownServiceError) Error ¶
func (e UnknownServiceError) Error() string
String returns the string representation of the error.
func (UnknownServiceError) String ¶
func (e UnknownServiceError) String() string
String returns the string representation of the error.
Source Files