CreateHttpNamespace

$result = $client->createHttpNamespace([/* ... */]);
$promise = $client->createHttpNamespaceAsync([/* ... */]);

Creates an HTTP namespace. Service instances registered using an HTTP namespace can be discovered using a DiscoverInstances request but can't be discovered using DNS.

For the current quota on the number of namespaces that you can create using the same Amazon Web Services account, see Cloud Map quotas in the Cloud Map Developer Guide.

Parameter Syntax

$result = $client->createHttpNamespace([
    'CreatorRequestId' => '<string>',
    'Description' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceAlreadyExists:

The namespace that you're trying to create already exists.

ResourceLimitExceeded:

The resource can't be created because you've reached the quota on the number of resources.

DuplicateRequest:

The operation is already in progress.

TooManyTagsException:

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

Examples

Example 1: CreateHttpNamespace example

This example creates an HTTP namespace.

$result = $client->createHttpNamespace([
    'CreatorRequestId' => 'example-creator-request-id-0001',
    'Description' => 'Example.com AWS Cloud Map HTTP Namespace',
    'Name' => 'example-http.com',
]);

Result syntax:

[
    'OperationId' => 'httpvoqozuhfet5kzxoxg-a-response-example',
]

CreatePrivateDnsNamespace

$result = $client->createPrivateDnsNamespace([/* ... */]);
$promise = $client->createPrivateDnsNamespaceAsync([/* ... */]);

Creates a private namespace based on DNS, which is visible only inside a specified Amazon VPC. The namespace defines your service naming scheme. For example, if you name your namespace example.com and name your service backend, the resulting DNS name for the service is backend.example.com. Service instances that are registered using a private DNS namespace can be discovered using either a DiscoverInstances request or using DNS. For the current quota on the number of namespaces that you can create using the same Amazon Web Services account, see Cloud Map quotas in the Cloud Map Developer Guide.

Parameter Syntax

$result = $client->createPrivateDnsNamespace([
    'CreatorRequestId' => '<string>',
    'Description' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Properties' => [
        'DnsProperties' => [ // REQUIRED
            'SOA' => [ // REQUIRED
                'TTL' => <integer>, // REQUIRED
            ],
        ],
    ],
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'Vpc' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceAlreadyExists:

The namespace that you're trying to create already exists.

ResourceLimitExceeded:

The resource can't be created because you've reached the quota on the number of resources.

DuplicateRequest:

The operation is already in progress.

TooManyTagsException:

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

Examples

Example 1: Example: Create private DNS namespace

Example: Create private DNS namespace

$result = $client->createPrivateDnsNamespace([
    'CreatorRequestId' => 'eedd6892-50f3-41b2-8af9-611d6e1d1a8c',
    'Name' => 'example.com',
    'Vpc' => 'vpc-1c56417b',
]);

Result syntax:

[
    'OperationId' => 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd',
]

CreatePublicDnsNamespace

$result = $client->createPublicDnsNamespace([/* ... */]);
$promise = $client->createPublicDnsNamespaceAsync([/* ... */]);

Creates a public namespace based on DNS, which is visible on the internet. The namespace defines your service naming scheme. For example, if you name your namespace example.com and name your service backend, the resulting DNS name for the service is backend.example.com. You can discover instances that were registered with a public DNS namespace by using either a DiscoverInstances request or using DNS. For the current quota on the number of namespaces that you can create using the same Amazon Web Services account, see Cloud Map quotas in the Cloud Map Developer Guide.

Parameter Syntax

$result = $client->createPublicDnsNamespace([
    'CreatorRequestId' => '<string>',
    'Description' => '<string>',
    'Name' => '<string>', // REQUIRED
    'Properties' => [
        'DnsProperties' => [ // REQUIRED
            'SOA' => [ // REQUIRED
                'TTL' => <integer>, // REQUIRED
            ],
        ],
    ],
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceAlreadyExists:

The namespace that you're trying to create already exists.

ResourceLimitExceeded:

The resource can't be created because you've reached the quota on the number of resources.

DuplicateRequest:

The operation is already in progress.

TooManyTagsException:

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

Examples

Example 1: CreatePublicDnsNamespace example

This example creates a public namespace based on DNS.

$result = $client->createPublicDnsNamespace([
    'CreatorRequestId' => 'example-creator-request-id-0003',
    'Description' => 'Example.com AWS Cloud Map Public DNS Namespace',
    'Name' => 'example-public-dns.com',
]);

Result syntax:

[
    'OperationId' => 'dns2voqozuhfet5kzxoxg-a-response-example',
]

CreateService

$result = $client->createService([/* ... */]);
$promise = $client->createServiceAsync([/* ... */]);

Creates a service. This action defines the configuration for the following entities:

• For public and private DNS namespaces, one of the following combinations of DNS records in Amazon Route 53:

  • A

  • AAAA

  • A and AAAA

  • SRV

  • CNAME

• Optionally, a health check

After you create the service, you can submit a RegisterInstance request, and Cloud Map uses the values in the configuration to create the specified entities.

For the current quota on the number of instances that you can register using the same namespace and using the same service, see Cloud Map quotas in the Cloud Map Developer Guide.

Parameter Syntax

$result = $client->createService([
    'CreatorRequestId' => '<string>',
    'Description' => '<string>',
    'DnsConfig' => [
        'DnsRecords' => [ // REQUIRED
            [
                'TTL' => <integer>, // REQUIRED
                'Type' => 'SRV|A|AAAA|CNAME', // REQUIRED
            ],
            // ...
        ],
        'NamespaceId' => '<string>',
        'RoutingPolicy' => 'MULTIVALUE|WEIGHTED',
    ],
    'HealthCheckConfig' => [
        'FailureThreshold' => <integer>,
        'ResourcePath' => '<string>',
        'Type' => 'HTTP|HTTPS|TCP', // REQUIRED
    ],
    'HealthCheckCustomConfig' => [
        'FailureThreshold' => <integer>,
    ],
    'Name' => '<string>', // REQUIRED
    'NamespaceId' => '<string>',
    'Tags' => [
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
    'Type' => 'HTTP',
]);

Parameter Details

Result Syntax

[
    'Service' => [
        'Arn' => '<string>',
        'CreateDate' => <DateTime>,
        'CreatorRequestId' => '<string>',
        'Description' => '<string>',
        'DnsConfig' => [
            'DnsRecords' => [
                [
                    'TTL' => <integer>,
                    'Type' => 'SRV|A|AAAA|CNAME',
                ],
                // ...
            ],
            'NamespaceId' => '<string>',
            'RoutingPolicy' => 'MULTIVALUE|WEIGHTED',
        ],
        'HealthCheckConfig' => [
            'FailureThreshold' => <integer>,
            'ResourcePath' => '<string>',
            'Type' => 'HTTP|HTTPS|TCP',
        ],
        'HealthCheckCustomConfig' => [
            'FailureThreshold' => <integer>,
        ],
        'Id' => '<string>',
        'InstanceCount' => <integer>,
        'Name' => '<string>',
        'NamespaceId' => '<string>',
        'Type' => 'HTTP|DNS_HTTP|DNS',
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ResourceLimitExceeded:

The resource can't be created because you've reached the quota on the number of resources.

NamespaceNotFound:

No namespace exists with the specified ID.

ServiceAlreadyExists:

The service can't be created because a service with the same name already exists.

TooManyTagsException:

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

Examples

Example 1: Example: Create service

Example: Create service

$result = $client->createService([
    'CreatorRequestId' => '567c1193-6b00-4308-bd57-ad38a8822d25',
    'DnsConfig' => [
        'DnsRecords' => [
            [
                'TTL' => 60,
                'Type' => 'A',
            ],
        ],
        'NamespaceId' => 'ns-ylexjili4cdxy3xm',
        'RoutingPolicy' => 'MULTIVALUE',
    ],
    'Name' => 'myservice',
    'NamespaceId' => 'ns-ylexjili4cdxy3xm',
]);

Result syntax:

[
    'Service' => [
        'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:service/srv-p5zdwlg5uvvzjita',
        'CreateDate' => ,
        'CreatorRequestId' => '567c1193-6b00-4308-bd57-ad38a8822d25',
        'DnsConfig' => [
            'DnsRecords' => [
                [
                    'TTL' => 60,
                    'Type' => 'A',
                ],
            ],
            'NamespaceId' => 'ns-ylexjili4cdxy3xm',
            'RoutingPolicy' => 'MULTIVALUE',
        ],
        'Id' => 'srv-p5zdwlg5uvvzjita',
        'Name' => 'myservice',
        'NamespaceId' => 'ns-ylexjili4cdxy3xm',
    ],
]

DeleteNamespace

$result = $client->deleteNamespace([/* ... */]);
$promise = $client->deleteNamespaceAsync([/* ... */]);

Deletes a namespace from the current account. If the namespace still contains one or more services, the request fails.

Parameter Syntax

$result = $client->deleteNamespace([
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceNotFound:

No namespace exists with the specified ID.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

DuplicateRequest:

The operation is already in progress.

Examples

Example 1: Example: Delete namespace

Example: Delete namespace

$result = $client->deleteNamespace([
    'Id' => 'ns-ylexjili4cdxy3xm',
]);

Result syntax:

[
    'OperationId' => 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k98y6drk',
]

DeleteService

$result = $client->deleteService([/* ... */]);
$promise = $client->deleteServiceAsync([/* ... */]);

Deletes a specified service. If the service still contains one or more registered instances, the request fails.

Parameter Syntax

$result = $client->deleteService([
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ServiceNotFound:

No service exists with the specified ID.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

Examples

Example 1: Example: Delete service

Example: Delete service

$result = $client->deleteService([
    'Id' => 'srv-p5zdwlg5uvvzjita',
]);

Result syntax:

[
]

DeregisterInstance

$result = $client->deregisterInstance([/* ... */]);
$promise = $client->deregisterInstanceAsync([/* ... */]);

Deletes the Amazon Route 53 DNS records and health check, if any, that Cloud Map created for the specified instance.

Parameter Syntax

$result = $client->deregisterInstance([
    'InstanceId' => '<string>', // REQUIRED
    'ServiceId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

DuplicateRequest:

The operation is already in progress.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

InstanceNotFound:

No instance exists with the specified ID, or the instance was recently registered, and information about the instance hasn't propagated yet.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: Example: Deregister a service instance

Example: Deregister a service instance

$result = $client->deregisterInstance([
    'InstanceId' => 'myservice-53',
    'ServiceId' => 'srv-p5zdwlg5uvvzjita',
]);

Result syntax:

[
    'OperationId' => '4yejorelbukcjzpnr6tlmrghsjwpngf4-k98rnaiq',
]

DiscoverInstances

$result = $client->discoverInstances([/* ... */]);
$promise = $client->discoverInstancesAsync([/* ... */]);

Discovers registered instances for a specified namespace and service. You can use DiscoverInstances to discover instances for any type of namespace. DiscoverInstances returns a randomized list of instances allowing customers to distribute traffic evenly across instances. For public and private DNS namespaces, you can also use DNS queries to discover instances.

Parameter Syntax

$result = $client->discoverInstances([
    'HealthStatus' => 'HEALTHY|UNHEALTHY|ALL|HEALTHY_OR_ELSE_ALL',
    'MaxResults' => <integer>,
    'NamespaceName' => '<string>', // REQUIRED
    'OptionalParameters' => ['<string>', ...],
    'QueryParameters' => ['<string>', ...],
    'ServiceName' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Instances' => [
        [
            'Attributes' => ['<string>', ...],
            'HealthStatus' => 'HEALTHY|UNHEALTHY|UNKNOWN',
            'InstanceId' => '<string>',
            'NamespaceName' => '<string>',
            'ServiceName' => '<string>',
        ],
        // ...
    ],
    'InstancesRevision' => <integer>,
]

Result Details

Errors

ServiceNotFound:

No service exists with the specified ID.

NamespaceNotFound:

No namespace exists with the specified ID.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

RequestLimitExceeded:

The operation can't be completed because you've reached the quota for the number of requests. For more information, see Cloud Map API request throttling quota in the Cloud Map Developer Guide.

Examples

Example 1: Example: Discover registered instances

Example: Discover registered instances

$result = $client->discoverInstances([
    'HealthStatus' => 'ALL',
    'MaxResults' => 10,
    'NamespaceName' => 'example.com',
    'ServiceName' => 'myservice',
]);

Result syntax:

[
    'Instances' => [
        [
            'Attributes' => [
                'AWS_INSTANCE_IPV4' => '172.2.1.3',
                'AWS_INSTANCE_PORT' => '808',
            ],
            'HealthStatus' => 'UNKNOWN',
            'InstanceId' => 'myservice-53',
            'NamespaceName' => 'example.com',
            'ServiceName' => 'myservice',
        ],
    ],
]

DiscoverInstancesRevision

$result = $client->discoverInstancesRevision([/* ... */]);
$promise = $client->discoverInstancesRevisionAsync([/* ... */]);

Discovers the increasing revision associated with an instance.

Parameter Syntax

$result = $client->discoverInstancesRevision([
    'NamespaceName' => '<string>', // REQUIRED
    'ServiceName' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'InstancesRevision' => <integer>,
]

Result Details

Errors

ServiceNotFound:

No service exists with the specified ID.

NamespaceNotFound:

No namespace exists with the specified ID.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

RequestLimitExceeded:

The operation can't be completed because you've reached the quota for the number of requests. For more information, see Cloud Map API request throttling quota in the Cloud Map Developer Guide.

Examples

Example 1: To discover the revision for a registered instance

The following example discovers the revision ID for a registered instance.

$result = $client->discoverInstancesRevision([
    'NamespaceName' => 'example-namespace',
    'ServiceName' => 'example-service',
]);

Result syntax:

[
    'InstancesRevision' => 123456,
]

GetInstance

$result = $client->getInstance([/* ... */]);
$promise = $client->getInstanceAsync([/* ... */]);

Gets information about a specified instance.

Parameter Syntax

$result = $client->getInstance([
    'InstanceId' => '<string>', // REQUIRED
    'ServiceId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Instance' => [
        'Attributes' => ['<string>', ...],
        'CreatorRequestId' => '<string>',
        'Id' => '<string>',
    ],
]

Result Details

Errors

InstanceNotFound:

No instance exists with the specified ID, or the instance was recently registered, and information about the instance hasn't propagated yet.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: GetInstance example

This example gets information about a specified instance.

$result = $client->getInstance([
    'InstanceId' => 'i-abcd1234',
    'ServiceId' => 'srv-e4anhexample0004',
]);

Result syntax:

[
    'Instance' => [
        'Attributes' => [
            'AWS_INSTANCE_IPV4' => '192.0.2.44',
            'AWS_INSTANCE_PORT' => '80',
            'color' => 'green',
            'region' => 'us-west-2',
            'stage' => 'beta',
        ],
        'Id' => 'i-abcd1234',
    ],
]

GetInstancesHealthStatus

$result = $client->getInstancesHealthStatus([/* ... */]);
$promise = $client->getInstancesHealthStatusAsync([/* ... */]);

Gets the current health status (Healthy, Unhealthy, or Unknown) of one or more instances that are associated with a specified service.

Parameter Syntax

$result = $client->getInstancesHealthStatus([
    'Instances' => ['<string>', ...],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ServiceId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'NextToken' => '<string>',
    'Status' => ['<string>', ...],
]

Result Details

Errors

InstanceNotFound:

No instance exists with the specified ID, or the instance was recently registered, and information about the instance hasn't propagated yet.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: GetInstancesHealthStatus example

This example gets the current health status of one or more instances that are associate with a specified service.

$result = $client->getInstancesHealthStatus([
    'ServiceId' => 'srv-e4anhexample0004',
]);

Result syntax:

[
    'Status' => [
        'i-abcd1234' => 'HEALTHY',
        'i-abcd1235' => 'UNHEALTHY',
    ],
]

GetNamespace

$result = $client->getNamespace([/* ... */]);
$promise = $client->getNamespaceAsync([/* ... */]);

Gets information about a namespace.

Parameter Syntax

$result = $client->getNamespace([
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Namespace' => [
        'Arn' => '<string>',
        'CreateDate' => <DateTime>,
        'CreatorRequestId' => '<string>',
        'Description' => '<string>',
        'Id' => '<string>',
        'Name' => '<string>',
        'Properties' => [
            'DnsProperties' => [
                'HostedZoneId' => '<string>',
                'SOA' => [
                    'TTL' => <integer>,
                ],
            ],
            'HttpProperties' => [
                'HttpName' => '<string>',
            ],
        ],
        'ServiceCount' => <integer>,
        'Type' => 'DNS_PUBLIC|DNS_PRIVATE|HTTP',
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceNotFound:

No namespace exists with the specified ID.

Examples

Example 1: GetNamespace example

This example gets information about a specified namespace.

$result = $client->getNamespace([
    'Id' => 'ns-e4anhexample0004',
]);

Result syntax:

[
    'Namespace' => [
        'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-e1tpmexample0001',
        'CreateDate' => ,
        'CreatorRequestId' => 'example-creator-request-id-0001',
        'Description' => 'Example.com AWS Cloud Map HTTP Namespace',
        'Id' => 'ns-e1tpmexample0001',
        'Name' => 'example-http.com',
        'Properties' => [
            'DnsProperties' => [
            ],
            'HttpProperties' => [
                'HttpName' => 'example-http.com',
            ],
        ],
        'Type' => 'HTTP',
    ],
]

GetOperation

$result = $client->getOperation([/* ... */]);
$promise = $client->getOperationAsync([/* ... */]);

Gets information about any operation that returns an operation ID in the response, such as a CreateHttpNamespace request.

Parameter Syntax

$result = $client->getOperation([
    'OperationId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Operation' => [
        'CreateDate' => <DateTime>,
        'ErrorCode' => '<string>',
        'ErrorMessage' => '<string>',
        'Id' => '<string>',
        'Status' => 'SUBMITTED|PENDING|SUCCESS|FAIL',
        'Targets' => ['<string>', ...],
        'Type' => 'CREATE_NAMESPACE|DELETE_NAMESPACE|UPDATE_NAMESPACE|UPDATE_SERVICE|REGISTER_INSTANCE|DEREGISTER_INSTANCE',
        'UpdateDate' => <DateTime>,
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

OperationNotFound:

No operation exists with the specified ID.

Examples

Example 1: Example: Get operation result

Example: Get operation result

$result = $client->getOperation([
    'OperationId' => 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd',
]);

Result syntax:

[
    'Operation' => [
        'CreateDate' => ,
        'Id' => 'gv4g5meo7ndmeh4fqskygvk23d2fijwa-k9302yzd',
        'Status' => 'SUCCESS',
        'Targets' => [
            'NAMESPACE' => 'ns-ylexjili4cdxy3xm',
        ],
        'Type' => 'CREATE_NAMESPACE',
        'UpdateDate' => ,
    ],
]

GetService

$result = $client->getService([/* ... */]);
$promise = $client->getServiceAsync([/* ... */]);

Gets the settings for a specified service.

Parameter Syntax

$result = $client->getService([
    'Id' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Service' => [
        'Arn' => '<string>',
        'CreateDate' => <DateTime>,
        'CreatorRequestId' => '<string>',
        'Description' => '<string>',
        'DnsConfig' => [
            'DnsRecords' => [
                [
                    'TTL' => <integer>,
                    'Type' => 'SRV|A|AAAA|CNAME',
                ],
                // ...
            ],
            'NamespaceId' => '<string>',
            'RoutingPolicy' => 'MULTIVALUE|WEIGHTED',
        ],
        'HealthCheckConfig' => [
            'FailureThreshold' => <integer>,
            'ResourcePath' => '<string>',
            'Type' => 'HTTP|HTTPS|TCP',
        ],
        'HealthCheckCustomConfig' => [
            'FailureThreshold' => <integer>,
        ],
        'Id' => '<string>',
        'InstanceCount' => <integer>,
        'Name' => '<string>',
        'NamespaceId' => '<string>',
        'Type' => 'HTTP|DNS_HTTP|DNS',
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: GetService Example

This example gets the settings for a specified service.

$result = $client->getService([
    'Id' => 'srv-e4anhexample0004',
]);

Result syntax:

[
    'Service' => [
        'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:service/srv-e4anhexample0004',
        'CreateDate' => ,
        'CreatorRequestId' => 'example-creator-request-id-0004',
        'Description' => 'Example.com AWS Cloud Map HTTP Service',
        'HealthCheckConfig' => [
            'FailureThreshold' => 3,
            'ResourcePath' => '/',
            'Type' => 'HTTPS',
        ],
        'Id' => 'srv-e4anhexample0004',
        'Name' => 'example-http-service',
        'NamespaceId' => 'ns-e4anhexample0004',
    ],
]

ListInstances

$result = $client->listInstances([/* ... */]);
$promise = $client->listInstancesAsync([/* ... */]);

Lists summary information about the instances that you registered by using a specified service.

Parameter Syntax

$result = $client->listInstances([
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
    'ServiceId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Instances' => [
        [
            'Attributes' => ['<string>', ...],
            'Id' => '<string>',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Errors

ServiceNotFound:

No service exists with the specified ID.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: Example: List service instances

Example: List service instances

$result = $client->listInstances([
    'ServiceId' => 'srv-qzpwvt2tfqcegapy',
]);

Result syntax:

[
    'Instances' => [
        [
            'Attributes' => [
                'AWS_INSTANCE_IPV4' => '172.2.1.3',
                'AWS_INSTANCE_PORT' => '808',
            ],
            'Id' => 'i-06bdabbae60f65a4e',
        ],
    ],
]

ListNamespaces

$result = $client->listNamespaces([/* ... */]);
$promise = $client->listNamespacesAsync([/* ... */]);

Lists summary information about the namespaces that were created by the current Amazon Web Services account.

Parameter Syntax

$result = $client->listNamespaces([
    'Filters' => [
        [
            'Condition' => 'EQ|IN|BETWEEN|BEGINS_WITH',
            'Name' => 'TYPE|NAME|HTTP_NAME', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'Namespaces' => [
        [
            'Arn' => '<string>',
            'CreateDate' => <DateTime>,
            'Description' => '<string>',
            'Id' => '<string>',
            'Name' => '<string>',
            'Properties' => [
                'DnsProperties' => [
                    'HostedZoneId' => '<string>',
                    'SOA' => [
                        'TTL' => <integer>,
                    ],
                ],
                'HttpProperties' => [
                    'HttpName' => '<string>',
                ],
            ],
            'ServiceCount' => <integer>,
            'Type' => 'DNS_PUBLIC|DNS_PRIVATE|HTTP',
        ],
        // ...
    ],
    'NextToken' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: Example: List namespaces

Example: List namespaces

$result = $client->listNamespaces([
]);

Result syntax:

[
    'Namespaces' => [
        [
            'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-a3ccy2e7e3a7rile',
            'CreateDate' => ,
            'Id' => 'ns-a3ccy2e7e3a7rile',
            'Name' => 'local',
            'Properties' => [
                'DnsProperties' => [
                    'HostedZoneId' => 'Z06752353VBUDTC32S84S',
                ],
                'HttpProperties' => [
                    'HttpName' => 'local',
                ],
            ],
            'Type' => 'DNS_PRIVATE',
        ],
        [
            'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-pocfyjtrsmwtvcxx',
            'CreateDate' => ,
            'Description' => 'My second namespace',
            'Id' => 'ns-pocfyjtrsmwtvcxx',
            'Name' => 'My-second-namespace',
            'Properties' => [
                'DnsProperties' => [
                ],
                'HttpProperties' => [
                    'HttpName' => 'My-second-namespace',
                ],
            ],
            'Type' => 'HTTP',
        ],
        [
            'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:namespace/ns-ylexjili4cdxy3xm',
            'CreateDate' => ,
            'Id' => 'ns-ylexjili4cdxy3xm',
            'Name' => 'example.com',
            'Properties' => [
                'DnsProperties' => [
                    'HostedZoneId' => 'Z09983722P0QME1B3KC8I',
                ],
                'HttpProperties' => [
                    'HttpName' => 'example.com',
                ],
            ],
            'Type' => 'DNS_PRIVATE',
        ],
    ],
]

ListOperations

$result = $client->listOperations([/* ... */]);
$promise = $client->listOperationsAsync([/* ... */]);

Lists operations that match the criteria that you specify.

Parameter Syntax

$result = $client->listOperations([
    'Filters' => [
        [
            'Condition' => 'EQ|IN|BETWEEN|BEGINS_WITH',
            'Name' => 'NAMESPACE_ID|SERVICE_ID|STATUS|TYPE|UPDATE_DATE', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'NextToken' => '<string>',
    'Operations' => [
        [
            'Id' => '<string>',
            'Status' => 'SUBMITTED|PENDING|SUCCESS|FAIL',
        ],
        // ...
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: ListOperations Example

This example gets the operations that have a STATUS of either PENDING or SUCCESS.

$result = $client->listOperations([
    'Filters' => [
        [
            'Condition' => 'IN',
            'Name' => 'STATUS',
            'Values' => [
                'PENDING',
                'SUCCESS',
            ],
        ],
    ],
]);

Result syntax:

[
    'Operations' => [
        [
            'Id' => '76yy8ovhpdz0plmjzbsnqgnrqvpv2qdt-kexample',
            'Status' => 'SUCCESS',
        ],
        [
            'Id' => 'prysnyzpji3u2ciy45nke83x2zanl7yk-dexample',
            'Status' => 'SUCCESS',
        ],
        [
            'Id' => 'ko4ekftir7kzlbechsh7xvcdgcpk66gh-7example',
            'Status' => 'PENDING',
        ],
    ],
]

ListServices

$result = $client->listServices([/* ... */]);
$promise = $client->listServicesAsync([/* ... */]);

Lists summary information for all the services that are associated with one or more namespaces.

Parameter Syntax

$result = $client->listServices([
    'Filters' => [
        [
            'Condition' => 'EQ|IN|BETWEEN|BEGINS_WITH',
            'Name' => 'NAMESPACE_ID', // REQUIRED
            'Values' => ['<string>', ...], // REQUIRED
        ],
        // ...
    ],
    'MaxResults' => <integer>,
    'NextToken' => '<string>',
]);

Parameter Details

Result Syntax

[
    'NextToken' => '<string>',
    'Services' => [
        [
            'Arn' => '<string>',
            'CreateDate' => <DateTime>,
            'Description' => '<string>',
            'DnsConfig' => [
                'DnsRecords' => [
                    [
                        'TTL' => <integer>,
                        'Type' => 'SRV|A|AAAA|CNAME',
                    ],
                    // ...
                ],
                'NamespaceId' => '<string>',
                'RoutingPolicy' => 'MULTIVALUE|WEIGHTED',
            ],
            'HealthCheckConfig' => [
                'FailureThreshold' => <integer>,
                'ResourcePath' => '<string>',
                'Type' => 'HTTP|HTTPS|TCP',
            ],
            'HealthCheckCustomConfig' => [
                'FailureThreshold' => <integer>,
            ],
            'Id' => '<string>',
            'InstanceCount' => <integer>,
            'Name' => '<string>',
            'Type' => 'HTTP|DNS_HTTP|DNS',
        ],
        // ...
    ],
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: Example: List services

Example: List services

$result = $client->listServices([
]);

Result syntax:

[
    'Services' => [
        [
            'Arn' => 'arn:aws:servicediscovery:us-west-2:123456789012:service/srv-p5zdwlg5uvvzjita',
            'CreateDate' => ,
            'DnsConfig' => [
                'DnsRecords' => [
                    [
                        'TTL' => 60,
                        'Type' => 'A',
                    ],
                ],
                'RoutingPolicy' => 'MULTIVALUE',
            ],
            'Id' => 'srv-p5zdwlg5uvvzjita',
            'Name' => 'myservice',
        ],
    ],
]

ListTagsForResource

$result = $client->listTagsForResource([/* ... */]);
$promise = $client->listTagsForResourceAsync([/* ... */]);

Lists tags for the specified resource.

Parameter Syntax

$result = $client->listTagsForResource([
    'ResourceARN' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'Tags' => [
        [
            'Key' => '<string>',
            'Value' => '<string>',
        ],
        // ...
    ],
]

Result Details

Errors

ResourceNotFoundException:

The operation can't be completed because the resource was not found.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: ListTagsForResource example

This example lists the tags of a resource.

$result = $client->listTagsForResource([
    'ResourceARN' => 'arn:aws:servicediscovery:us-east-1:123456789012:namespace/ns-ylexjili4cdxy3xm',
]);

Result syntax:

[
    'Tags' => [
        [
            'Key' => 'Project',
            'Value' => 'Zeta',
        ],
        [
            'Key' => 'Department',
            'Value' => 'Engineering',
        ],
    ],
]

RegisterInstance

$result = $client->registerInstance([/* ... */]);
$promise = $client->registerInstanceAsync([/* ... */]);

Creates or updates one or more records and, optionally, creates a health check based on the settings in a specified service. When you submit a RegisterInstance request, the following occurs:

• For each DNS record that you define in the service that's specified by ServiceId, a record is created or updated in the hosted zone that's associated with the corresponding namespace.

• If the service includes HealthCheckConfig, a health check is created based on the settings in the health check configuration.

• The health check, if any, is associated with each of the new or updated records.

For more information, see CreateService.

When Cloud Map receives a DNS query for the specified DNS name, it returns the applicable value:

• If the health check is healthy: returns all the records

• If the health check is unhealthy: returns the applicable value for the last healthy instance

• If you didn't specify a health check configuration: returns all the records

For the current quota on the number of instances that you can register using the same namespace and using the same service, see Cloud Map quotas in the Cloud Map Developer Guide.

Parameter Syntax

$result = $client->registerInstance([
    'Attributes' => ['<string>', ...], // REQUIRED
    'CreatorRequestId' => '<string>',
    'InstanceId' => '<string>', // REQUIRED
    'ServiceId' => '<string>', // REQUIRED
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

DuplicateRequest:

The operation is already in progress.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

ResourceLimitExceeded:

The resource can't be created because you've reached the quota on the number of resources.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: Example: Register Instance

Example: Register Instance

$result = $client->registerInstance([
    'Attributes' => [
        'AWS_INSTANCE_IPV4' => '172.2.1.3',
        'AWS_INSTANCE_PORT' => '808',
    ],
    'CreatorRequestId' => '7a48a98a-72e6-4849-bfa7-1a458e030d7b',
    'InstanceId' => 'myservice-53',
    'ServiceId' => 'srv-p5zdwlg5uvvzjita',
]);

Result syntax:

[
    'OperationId' => '4yejorelbukcjzpnr6tlmrghsjwpngf4-k95yg2u7',
]

TagResource

$result = $client->tagResource([/* ... */]);
$promise = $client->tagResourceAsync([/* ... */]);

Adds one or more tags to the specified resource.

Parameter Syntax

$result = $client->tagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'Tags' => [ // REQUIRED
        [
            'Key' => '<string>', // REQUIRED
            'Value' => '<string>', // REQUIRED
        ],
        // ...
    ],
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

ResourceNotFoundException:

The operation can't be completed because the resource was not found.

TooManyTagsException:

The list of tags on the resource is over the quota. The maximum number of tags that can be applied to a resource is 50.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: TagResource example

This example adds "Department" and "Project" tags to a resource.

$result = $client->tagResource([
    'ResourceARN' => 'arn:aws:servicediscovery:us-east-1:123456789012:namespace/ns-ylexjili4cdxy3xm',
    'Tags' => [
        [
            'Key' => 'Department',
            'Value' => 'Engineering',
        ],
        [
            'Key' => 'Project',
            'Value' => 'Zeta',
        ],
    ],
]);

Result syntax:

[
]

UntagResource

$result = $client->untagResource([/* ... */]);
$promise = $client->untagResourceAsync([/* ... */]);

Removes one or more tags from the specified resource.

Parameter Syntax

$result = $client->untagResource([
    'ResourceARN' => '<string>', // REQUIRED
    'TagKeys' => ['<string>', ...], // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

ResourceNotFoundException:

The operation can't be completed because the resource was not found.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: UntagResource example

This example removes the "Department" and "Project" tags from a resource.

$result = $client->untagResource([
    'ResourceARN' => 'arn:aws:servicediscovery:us-east-1:123456789012:namespace/ns-ylexjili4cdxy3xm',
    'TagKeys' => [
        'Project',
        'Department',
    ],
]);

Result syntax:

[
]

UpdateHttpNamespace

$result = $client->updateHttpNamespace([/* ... */]);
$promise = $client->updateHttpNamespaceAsync([/* ... */]);

Updates an HTTP namespace.

Parameter Syntax

$result = $client->updateHttpNamespace([
    'Id' => '<string>', // REQUIRED
    'Namespace' => [ // REQUIRED
        'Description' => '<string>', // REQUIRED
    ],
    'UpdaterRequestId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceNotFound:

No namespace exists with the specified ID.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

DuplicateRequest:

The operation is already in progress.

Examples

Example 1: To update a HTTP namespace

The following example updates the description of a HTTP namespace.

$result = $client->updateHttpNamespace([
    'Id' => 'ns-vh4nbmEXAMPLE',
    'Namespace' => [
        'Description' => 'The updated namespace description.',
    ],
]);

Result syntax:

[
    'OperationId' => 'ft52xe2koxhoeormaceymagglsdjyvEXAMPLE',
]

UpdateInstanceCustomHealthStatus

$result = $client->updateInstanceCustomHealthStatus([/* ... */]);
$promise = $client->updateInstanceCustomHealthStatusAsync([/* ... */]);

Submits a request to change the health status of a custom health check to healthy or unhealthy.

You can use UpdateInstanceCustomHealthStatus to change the status only for custom health checks, which you define using HealthCheckCustomConfig when you create a service. You can't use it to change the status for Route 53 health checks, which you define using HealthCheckConfig.

For more information, see HealthCheckCustomConfig.

Parameter Syntax

$result = $client->updateInstanceCustomHealthStatus([
    'InstanceId' => '<string>', // REQUIRED
    'ServiceId' => '<string>', // REQUIRED
    'Status' => 'HEALTHY|UNHEALTHY', // REQUIRED
]);

Parameter Details

Result Syntax

[]

Result Details

Errors

InstanceNotFound:

No instance exists with the specified ID, or the instance was recently registered, and information about the instance hasn't propagated yet.

ServiceNotFound:

No service exists with the specified ID.

CustomHealthNotFound:

The health check for the instance that's specified by ServiceId and InstanceId isn't a custom health check.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

Examples

Example 1: UpdateInstanceCustomHealthStatus Example

This example submits a request to change the health status of an instance associated with a service with a custom health check to HEALTHY.

$result = $client->updateInstanceCustomHealthStatus([
    'InstanceId' => 'i-abcd1234',
    'ServiceId' => 'srv-e4anhexample0004',
    'Status' => 'HEALTHY',
]);

UpdatePrivateDnsNamespace

$result = $client->updatePrivateDnsNamespace([/* ... */]);
$promise = $client->updatePrivateDnsNamespaceAsync([/* ... */]);

Updates a private DNS namespace.

Parameter Syntax

$result = $client->updatePrivateDnsNamespace([
    'Id' => '<string>', // REQUIRED
    'Namespace' => [ // REQUIRED
        'Description' => '<string>',
        'Properties' => [
            'DnsProperties' => [ // REQUIRED
                'SOA' => [ // REQUIRED
                    'TTL' => <integer>, // REQUIRED
                ],
            ],
        ],
    ],
    'UpdaterRequestId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceNotFound:

No namespace exists with the specified ID.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

DuplicateRequest:

The operation is already in progress.

Examples

Example 1: To update a private DNS namespace

The following example updates the description of a private DNS namespace.

$result = $client->updatePrivateDnsNamespace([
    'Id' => 'ns-bk3aEXAMPLE',
    'Namespace' => [
        'Description' => 'The updated namespace description.',
    ],
    'UpdaterRequestId' => '',
]);

Result syntax:

[
    'OperationId' => 'ft52xe2koxhoeormaceymagglsdjyvEXAMPLE',
]

Example 2: To update a public DNS namespace

The following example updates the description of a public DNS namespace.

$result = $client->updatePrivateDnsNamespace([
    'Id' => 'ns-bk3aEXAMPLE',
    'Namespace' => [
        'Description' => 'The updated namespace description.',
    ],
    'UpdaterRequestId' => '',
]);

Result syntax:

[
    'OperationId' => 'ft52xe2koxhoeormaceymagglsdjEXAMPLE',
]

UpdatePublicDnsNamespace

$result = $client->updatePublicDnsNamespace([/* ... */]);
$promise = $client->updatePublicDnsNamespaceAsync([/* ... */]);

Updates a public DNS namespace.

Parameter Syntax

$result = $client->updatePublicDnsNamespace([
    'Id' => '<string>', // REQUIRED
    'Namespace' => [ // REQUIRED
        'Description' => '<string>',
        'Properties' => [
            'DnsProperties' => [ // REQUIRED
                'SOA' => [ // REQUIRED
                    'TTL' => <integer>, // REQUIRED
                ],
            ],
        ],
    ],
    'UpdaterRequestId' => '<string>',
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

NamespaceNotFound:

No namespace exists with the specified ID.

ResourceInUse:

The specified resource can't be deleted because it contains other resources. For example, you can't delete a service that contains any instances.

DuplicateRequest:

The operation is already in progress.

UpdateService

$result = $client->updateService([/* ... */]);
$promise = $client->updateServiceAsync([/* ... */]);

Submits a request to perform the following operations:

• Update the TTL setting for existing DnsRecords configurations

• Add, update, or delete HealthCheckConfig for a specified service

  You can't add, update, or delete a HealthCheckCustomConfig configuration.

For public and private DNS namespaces, note the following:

• If you omit any existing DnsRecords or HealthCheckConfig configurations from an UpdateService request, the configurations are deleted from the service.

• If you omit an existing HealthCheckCustomConfig configuration from an UpdateService request, the configuration isn't deleted from the service.

When you update settings for a service, Cloud Map also updates the corresponding settings in all the records and health checks that were created by using the specified service.

Parameter Syntax

$result = $client->updateService([
    'Id' => '<string>', // REQUIRED
    'Service' => [ // REQUIRED
        'Description' => '<string>',
        'DnsConfig' => [
            'DnsRecords' => [ // REQUIRED
                [
                    'TTL' => <integer>, // REQUIRED
                    'Type' => 'SRV|A|AAAA|CNAME', // REQUIRED
                ],
                // ...
            ],
        ],
        'HealthCheckConfig' => [
            'FailureThreshold' => <integer>,
            'ResourcePath' => '<string>',
            'Type' => 'HTTP|HTTPS|TCP', // REQUIRED
        ],
    ],
]);

Parameter Details

Result Syntax

[
    'OperationId' => '<string>',
]

Result Details

Errors

DuplicateRequest:

The operation is already in progress.

InvalidInput:

One or more specified values aren't valid. For example, a required value might be missing, a numeric value might be outside the allowed range, or a string value might exceed length constraints.

ServiceNotFound:

No service exists with the specified ID.

Examples

Example 1: UpdateService Example

This example submits a request to replace the DnsConfig and HealthCheckConfig settings of a specified service.

$result = $client->updateService([
    'Id' => 'srv-e4anhexample0004',
    'Service' => [
        'DnsConfig' => [
            'DnsRecords' => [
                [
                    'TTL' => 60,
                    'Type' => 'A',
                ],
            ],
        ],
        'HealthCheckConfig' => [
            'FailureThreshold' => 2,
            'ResourcePath' => '/',
            'Type' => 'HTTP',
        ],
    ],
]);

Result syntax:

[
    'OperationId' => 'm35hsdrkxwjffm3xef4bxyy6vc3ewakx-jdn3y5g5',
]