Restore S3 objects

POST /api/meta/entity/bulk#restoreS3Objects

Restore one or more soft-deleted (archived) S3 objects.

The restoration relies on matches being found for the provided qualifiedNames. If the this does not exactly match (case-sensitive) a soft-deleted S3 object's qualifiedName, the request will fail.

Note that the guid is also required to avoid accidentally creating a new S3 object. If the qualifiedName does not match an existing S3 object, and no guid is supplied in the request, then this endpoint will create a new S3 object with the provided details.

Body Required

List of S3 objects to restore.

  • entities array[object] Required

    Instance of an S3 object asset in Atlan, with its detailed information.

    • typeName string Required

      Should always be S3Object.

    • attributes object Required

      Attributes that can exist in S3 object assets in Atlan.

      • qualifiedName string Required

        Unique name for this S3 object. This is usually the concatenation of the parent bucket's qualifiedName with the s3ObjectKey, separated by a /.

      • name string Required

        Human-readable name of the S3 object.

      • awsArn string | null Required

        Amazon Resource Name (ARN) for this asset. This uniquely identifies the asset in AWS, and thus must be unique across all AWS asset instances.

      • awsPartition string | null

        Group of AWS region and service objects.

      • awsService string | null

        Type of service in which the asset exists.

      • awsRegion string | null

        Physical region where the data center in which the asset exists is clustered.

      • awsAccountId string | null

        12-digit number that uniquely identifies an AWS account.

      • awsResourceId string | null

        Unique resource ID assigned when a new resource is created.

      • awsOwnerName string | null

        Root user's name.

      • awsOwnerId string | null

        Root user's ID.

      • awsTags array[object] | null

        List of tags that have been applied to the asset in AWS.

      • connectorName string Required

        Name of the connector. For S3, this should always be s3.

      • s3ETag string | null

        Entity tag for the asset. An entity tag is a hash of the object and represents changes to the contents of an object only, not its metadata.

      • s3Encryption string | null
      • s3ObjectLastModifiedTime integer | null

        Time (epoch) at which the object was last updated, in milliseconds, or when it was created if it has never been modified.

      • s3BucketName string | null

        Name of the bucket in which the object exists.

      • s3BucketQualifiedName string | null Required

        Qualified name of the bucket in which the object exists.

      • s3ObjectSize integer | null

        Object size in bytes.

      • s3ObjectStorageClass string | null

        Storage class used for storing the object.

      • s3ObjectKey string | null Required

        Unique identity of the object in an S3 bucket. This is usually the concatenation of any prefix (folder) in the S3 bucket with the name of the object (file) itself.

      • s3ObjectContentType string | null

        Type of content in the object.

      • s3ObjectContentDisposition string | null

        Information about how the object's content should be presented.

      • s3ObjectVersionId string | null

        Version of the object. This is only applicable when versioning is enabled on the bucket in which the object exists.

    • relationshipAttributes object Required

      Relationships that can exist for S3 object assets in Atlan.

      • bucket object Required

        Details to use within an asset when referring to a S3 bucket.

        • typeName string

          Should always be S3Bucket.

        • guid string | null

          Unique identifier of the related S3 bucket. If the uniqueAttributes are not provided, this must be provided.

        • uniqueAttributes object | null

          Attribute(s) that uniquely identify the related S3 bucket. If the guid is not provided, these must be provided.

Responses

  • • 200 object

    S3 objects that were successfully restored (undeleted).

    • mutatedEntities object | null

      S3 objects that were restored.

      • UPDATE array[object]

        Instance of an S3 object asset in Atlan, with its detailed information.

        • typeName string

          Should always be S3Object.

        • attributes object | null

          Attributes that can exist in S3 object assets in Atlan.

          • qualifiedName string

            Unique name for this S3 object. This is usually the concatenation of the parent bucket's qualifiedName with the s3ObjectKey, separated by a /.

          • name string

            Human-readable name of the S3 object.

          • displayName string | null

            Name used for display purposes (in user interfaces).

          • description string | null

            Description of the asset, as crawled from a source.

          • userDescription string | null

            Description of the asset, as provided by a user. If present, this will be used for the description in user interfaces. If not present, the description will be used.

          • tenantId string | null

            Name of the Atlan workspace in which the table exists.

          • certificateStatus string | null

            Status of the asset's certification.

            Values are VERIFIED, DRAFT, DEPRECATED, or null.

          • certificateStatusMessage string | null

            Human-readable descriptive message that can optionally be submitted when the certificateStatus is changed.

          • announcementTitle string | null

            Brief title for the announcement on this asset. Required when announcementType is specified.

          • announcementMessage string | null

            Detailed message to include in the announcement on this asset.

          • announcementType string | null

            Type of announcement on the asset.

            Values are information, warning, issue, or null.

          • ownerUsers array[string] | null

            List of users who own the asset.

          • ownerGroups array[string] | null

            List of groups who own the asset.

          • adminUsers array[string] | null

            List of users who administer the asset. (This is only used for Connection assets.)

          • adminGroups array[string] | null

            List of groups who administer the asset. (This is only used for Connection assets.)

          • viewerUsers array[string] | null
          • viewerGroups array[string] | null
          • connectorName string | null

            Name of the connector. For S3, this should always be s3.

          • connectionName string | null Deprecated

            Unused.

          • connectionQualifiedName string | null

            Unique name of the connection through which this asset is accessible.

          • isDiscoverable boolean | null
          • isEditable boolean | null
          • subType object | null
          • viewScore number | null
          • popularityScore number | null
          • sourceOwners array[string] | null
          • sourceURL string | null
          • lastSyncWorkflowName string | null

            Name of the crawler that last synchronized this asset.

          • lastSyncRunAt integer | null

            Time (epoch) at which the table was last crawled, in milliseconds.

          • lastSyncRun string | null

            Name of the last run of the crawler that last synchronized this asset.

          • certificateUpdatedBy string | null

            Name of the user who last updated the certificateStatus.

          • certificateUpdatedAt integer | null

            Time (epoch) at which the certificateStatus was last updated, in milliseconds.

          • announcementUpdatedAt integer | null

            Time (epoch) at which the announcement was last updated, in milliseconds.

          • announcementUpdatedBy string | null

            User who last updated the announcement.

          • sourceCreatedBy string | null
          • sourceCreatedAt integer | null
          • sourceUpdatedAt integer | null
          • sourceUpdatedBy string | null
          • awsArn string | null

            Amazon Resource Name (ARN) for this asset. This uniquely identifies the asset in AWS, and thus must be unique across all AWS asset instances.

          • awsPartition string | null

            Group of AWS region and service objects.

          • awsService string | null

            Type of service in which the asset exists.

          • awsRegion string | null

            Physical region where the data center in which the asset exists is clustered.

          • awsAccountId string | null

            12-digit number that uniquely identifies an AWS account.

          • awsResourceId string | null

            Unique resource ID assigned when a new resource is created.

          • awsOwnerName string | null

            Root user's name.

          • awsOwnerId string | null

            Root user's ID.

          • awsTags array[object] | null

            List of tags that have been applied to the asset in AWS.

          • s3ETag string | null

            Entity tag for the asset. An entity tag is a hash of the object and represents changes to the contents of an object only, not its metadata.

          • s3Encryption string | null
          • s3ObjectLastModifiedTime integer | null

            Time (epoch) at which the object was last updated, in milliseconds, or when it was created if it has never been modified.

          • s3BucketName string | null

            Name of the bucket in which the object exists.

          • s3BucketQualifiedName string | null

            Qualified name of the bucket in which the object exists.

          • s3ObjectSize integer | null

            Object size in bytes.

          • s3ObjectStorageClass string | null

            Storage class used for storing the object.

          • s3ObjectKey string | null

            Unique identity of the object in an S3 bucket. This is usually the concatenation of any prefix (folder) in the S3 bucket with the name of the object (file) itself.

          • s3ObjectContentType string | null

            Type of content in the object.

          • s3ObjectContentDisposition string | null

            Information about how the object's content should be presented.

          • s3ObjectVersionId string | null

            Version of the object. This is only applicable when versioning is enabled on the bucket in which the object exists.

        • classifications array[object] | null

          Instance of a classification in Atlan, with its detailed information.

          • typeName string

            Name of the classification. Note that this is the static-hashed unique name of the classification, not the human-readable displayName.

          • entityGuid string

            Unique identifier of the entity to which this classification is attached.

          • propagate boolean | null

            Whether to propagate this classification to other entities related to the entity to which the classification is attached.

          • removePropagationsOnEntityDelete boolean | null

            Whether to remove this classification from other entities to which it has been propagated when the classification is removed from this entity.

          • entityStatus string | null

            Status of the entity to which this classification is attached.

            Values are ACTIVE or DELETED.

        • displayText string | null

          Human-readable name of the entity.

        • guid string

          Unique identifier of the entity instance.

        • isIncomplete boolean | null

          Default value is false.

        • createdBy string | null

          Username of the user who created the object.

        • updatedBy string | null

          Username of the user who last updated the object.

        • createTime integer | null

          Time (epoch) at which this object was created, in milliseconds.

        • updateTime integer | null

          Time (epoch) at which this object was last updated, in milliseconds.

        • version integer | null

          Version of this object.

        • classificationNames array[string] | null

          List of classifications for this entity. Note that these are the internal hashed names used in Atlan, not the displayText of the classification.

        • labels array[string] | null

          Internal use only.

        • status string

          Status of the entity, either ACTIVE or DELETED.

          Values are ACTIVE or DELETED.

        • relationshipAttributes object | null

          Relationships that can exist for S3 object assets in Atlan.

          • links array[object] | null

            Details to use within an asset when referring to a link (resource).

          • readme object

            Details to use within an asset when referring to a readme.

            • typeName string

              Should always be Readme.

            • guid string | null

              Unique identifier of the related readme. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related readme. If the guid is not provided, these must be provided.

          • meanings array[object] | null

            Details to use within an asset when referring to a term.

            • typeName string

              Should always be AtlasnGlossaryTerm.

            • guid string | null

              Unique identifier of the related term. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related term. If the guid is not provided, these must be provided.

              • qualifiedName string

                Unique name of the related term. Note that in Atlan this unique name is a hashed value, not the name you see in the UI.

          • bucket object

            Details to use within an asset when referring to a S3 bucket.

            • typeName string

              Should always be S3Bucket.

            • guid string | null

              Unique identifier of the related S3 bucket. If the uniqueAttributes are not provided, this must be provided.

            • uniqueAttributes object | null

              Attribute(s) that uniquely identify the related S3 bucket. If the guid is not provided, these must be provided.

    • guidAssignments object

      Map of assigned unique identifiers for any created S3 objects (should be empty for restored S3 objects).

  • • 404 object

    S3 object could not be found by the qualifiedName or guid provided.

    • errorCode string

      Unique code for the type of error that occurred.

    • errorMessage string

      Human-readable description of the error that occurred.

    • entityGuid string

      GUID that could not be found

POST /api/meta/entity/bulk#restoreS3Objects 
curl \
 -X POST https://tenant.atlan.com/api/meta/entity/bulk#restoreS3Objects \
 -H "Authorization: Bearer $ACCESS_TOKEN" \
 -H "Content-Type: application/json" \
 -d '{"entities":[{"typeName":"S3Object","attributes":{"name":"my-file.csv","s3ObjectKey":"a/prefix/my-file.csv","connectorName":"s3","connectionQualifiedName":"default/s3/production","s3BucketQualifiedName":"default/s3/production/my-bucket","qualifiedName":"default/s3/production/my-bucket/a/prefix/my-file.csv","awsArn":"aws::production:my-bucket:a/prefix/my-file.csv"},"relationshipAttributes":{"bucket":{"guid":"f5740924-fe74-4462-96ff-5da0bc970cec","typeName":"S3Bucket"}},"guid":"23d6ec91-9399-41bf-8427-5cc91caaa42d","status":"ACTIVE"}]}'
Request example 
{
  "entities": [
    {
      "typeName": "S3Object",
      "attributes": {
        "name": "my-file.csv",
        "s3ObjectKey": "a/prefix/my-file.csv",
        "connectorName": "s3",
        "connectionQualifiedName": "default/s3/production",
        "s3BucketQualifiedName": "default/s3/production/my-bucket",
        "qualifiedName": "default/s3/production/my-bucket/a/prefix/my-file.csv",
        "awsArn": "aws::production:my-bucket:a/prefix/my-file.csv"
      },
      "relationshipAttributes": {
        "bucket": {
          "guid": "f5740924-fe74-4462-96ff-5da0bc970cec",
          "typeName": "S3Bucket"
        }
      },
      "guid": "23d6ec91-9399-41bf-8427-5cc91caaa42d",
      "status": "ACTIVE"
    }
  ]
}
Response example (200) 
{
  "mutatedEntities": {
    "UPDATE": [
      {
        "typeName": "S3Object",
        "attributes": {
          "popularityScore": 1.17549435e-38,
          "sourceCreatedAt": 0,
          "viewerUsers": [],
          "viewScore": 1.17549435e-38,
          "lastSyncRunAt": 0,
          "connectionQualifiedName": "default/s3/production",
          "adminGroups": [],
          "s3ObjectSize": 0,
          "qualifiedName": "default/s3/production/my-bucket/a/prefix/my-file.csv",
          "s3ObjectKey": "a/prefix/my-file.csv",
          "awsArn": "aws::production:my-bucket:a/prefix/my-file.csv",
          "__hasLineage": false,
          "adminUsers": [],
          "s3ObjectLastModifiedTime": 0,
          "ownerGroups": [],
          "isEditable": true,
          "sourceUpdatedAt": 0,
          "announcementUpdatedAt": 0,
          "name": "my-file.csv",
          "certificateUpdatedAt": 0,
          "connectorName": "s3",
          "s3BucketQualifiedName": "default/s3/production/my-bucket",
          "isDiscoverable": true,
          "viewerGroups": [],
          "ownerUsers": [],
          "awsTags": []
        },
        "guid": "23d6ec91-9399-41bf-8427-5cc91caaa42d",
        "status": "ACTIVE",
        "displayText": "my-file.csv",
        "classificationNames": [],
        "classifications": [],
        "meaningNames": [],
        "meanings": [],
        "isIncomplete": false,
        "labels": [],
        "createdBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "updatedBy": "service-account-apikey-bea1e1d1-e4e7-465e-8adf-7c61c227a59b",
        "createTime": 1652796499504,
        "updateTime": 1652796499504
      }
    ]
  },
  "guidAssignments": {}
}
Response example (404) 
{
  "errorCode": "ATLAS-404-00-00A",
  "errorMessage": "Referenced entity 23d6ec91-9399-41bf-8427-5cc91caaa42d is not found",
  "entityGuid": "23d6ec91-9399-41bf-8427-5cc91caaa42d"
}