1. Oracle GoldenGate 23ai Microservices Architecture REST API Documentation
  2. Tasks
  3. Administration Service
  4. Extracts

Create Extract

post

/services/{version}/extracts/{extract}

Required Role: Administrator

Create a new extract process.

Request

Supported Media Types
Path Parameters
  • Minimum Length: 1
    Maximum Length: 8
    Pattern: ^[A-Z_$][A-Z0-9_$]*$

    The name of the extract. Extract names are upper case, begin with an alphabetic character followed by up to seven alpha-numeric characters.

  • Oracle GoldenGate Service API version.

    Allowed Values: [ "v2" ]
Body ()
Root Schema : Oracle GoldenGate Extract
Type: object
Title: Oracle GoldenGate Extract
Show Source
Nested Schema : alias
Type: object
Show Source
Nested Schema : begin
Starting point for data processing
Default Value: now
Match One
Show Source
  • Allowed Values: [ "now" ]
  • Minimum Length: 20
    Maximum Length: 32
    Pattern: ^[0-9]{4}[-](0[1-9]|1[0-2])[-](0[1-9]|[12][0-9]|3[01])[tT ]([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]{1,6})?([zZ]|[+-][0-9][0-9]:[0-5][0-9])$
  • begin-x-oneOf[2]
Nested Schema : config
Type: array
Minimum Number of Items: 0
Maximum Number of Items: 32767
Show Source
Nested Schema : credentials
Credentials for source database
Default Value: oracle.doceng.json.BetterJsonNull@4346808
Match One
Show Source
Nested Schema : encryptionProfile
Match One
Show Source
  • Minimum Length: 1
    Maximum Length: 64
    Pattern: ^[A-Za-z0-9][A-Za-z0-9_:-]*$
    Name of 'ogg:encryptionProfile' configuration value
Nested Schema : managedProcessSettings
Control how the ER process is managed by the Administration Server
Match One
Show Source
Nested Schema : miningCredentials
Credentials for downstream mining database
Default Value: oracle.doceng.json.BetterJsonNull@bf75b5c
Match One
Show Source
Nested Schema : registration
Registration with the source database
Default Value: none
Match One
Show Source
Nested Schema : source
Source of data to process
Match One
Show Source
  • Allowed Values: [ "tables" ]
    Use tables (initial load)
  • Allowed Values: [ "tranlogs" ]
    Use transaction logs with change data capture
  • source-x-oneOf[2]
    OGG 19c Syntax NO LONGER SUPPORTED
Nested Schema : targets
Type: array
Minimum Number of Items: 0
Maximum Number of Items: 1024
Targets for captured data
Show Source
Nested Schema : manager
Type: object
Manager server to use
Show Source
Nested Schema : proxy
Type: object
Show Source
Nested Schema : host
Host name or IP Address
Match One
Show Source
  • Minimum Length: 1
    Maximum Length: 4095
    Pattern: ^(((([a-zA-Z0-9][-a-zA-Z0-9]{0,61})?[a-zA-Z0-9])[.])*([a-zA-Z][-a-zA-Z0-9]{0,61}[a-zA-Z0-9]|[a-zA-Z])[.]?)$
    Network host name
  • host-x-oneOf[1]
    Network IP address
Nested Schema : host-x-oneOf[1]
Network IP address
Match One
Show Source
  • Minimum Length: 7
    Maximum Length: 15
    Pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)[.]){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$
    Network IPv4 address
  • Minimum Length: 1
    Maximum Length: 256
    Pattern: ^((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:)))(%.+)?$
    Network IPv6 address
Nested Schema : credentials
Proxy server credentials
Default Value: oracle.doceng.json.BetterJsonNull@79d3473e
Match One
Show Source
Nested Schema : host
Proxy server host name or IP address
Match One
Show Source
  • Minimum Length: 1
    Maximum Length: 4095
    Pattern: ^(((([a-zA-Z0-9][-a-zA-Z0-9]{0,61})?[a-zA-Z0-9])[.])*([a-zA-Z][-a-zA-Z0-9]{0,61}[a-zA-Z0-9]|[a-zA-Z])[.]?)$
    Network host name
  • host-x-oneOf[1]
    Network IP address
Nested Schema : credentials-x-oneOf[0]
Type: object
Show Source
  • Allowed Values: [ "ogg:credentialsRef" ]
  • Minimum Length: 1
    Maximum Length: 30
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
  • Minimum Length: 1
    Maximum Length: 30
    Default Value: OracleGoldenGate
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
Nested Schema : host-x-oneOf[1]
Network IP address
Match One
Show Source
  • Minimum Length: 7
    Maximum Length: 15
    Pattern: ^((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)[.]){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)$
    Network IPv4 address
  • Minimum Length: 1
    Maximum Length: 256
    Pattern: ^((([0-9A-Fa-f]{1,4}:){7}([0-9A-Fa-f]{1,4}|:))|(([0-9A-Fa-f]{1,4}:){6}(:[0-9A-Fa-f]{1,4}|((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3})|:))|(([0-9A-Fa-f]{1,4}:){5}(((:[0-9A-Fa-f]{1,4}){1,2})|:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3})|:))|(([0-9A-Fa-f]{1,4}:){4}(((:[0-9A-Fa-f]{1,4}){1,3})|((:[0-9A-Fa-f]{1,4})((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){3}(((:[0-9A-Fa-f]{1,4}){1,4})|((:[0-9A-Fa-f]{1,4}){0,2}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){2}(((:[0-9A-Fa-f]{1,4}){1,5})|((:[0-9A-Fa-f]{1,4}){0,3}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(([0-9A-Fa-f]{1,4}:){1}(((:[0-9A-Fa-f]{1,4}){1,6})|((:[0-9A-Fa-f]{1,4}){0,4}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:))|(:(((:[0-9A-Fa-f]{1,4}){1,7})|((:[0-9A-Fa-f]{1,4}){0,5}:((25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])([.](25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9]?[0-9])){3}))|:)))(%.+)?$
    Network IPv6 address
Nested Schema : begin-x-oneOf[2]
Type: object
Show Source
Nested Schema : at
Type: object
Position at a specific SCN (integrated mode)
Show Source
Nested Schema : csn
Match One
Show Source
  • Minimum Value: 0
    Maximum Value: 9223372036854776000
    System Change Number(Normal Format) for Oracle Database.
    Example: 6488359
  • Minimum Length: 3
    Maximum Length: 64
    Pattern: [0-9]+[.][0-9]+
    System Change Number(Alternate Format) for Oracle Database.
    Example: 6488359.3456712
Nested Schema : credentials-x-oneOf[0]
Type: object
Show Source
  • Allowed Values: [ "ogg:credentialsRef" ]
  • Minimum Length: 1
    Maximum Length: 30
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
  • Minimum Length: 1
    Maximum Length: 30
    Default Value: OracleGoldenGate
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
Nested Schema : managedProcessSettings-x-oneOf[0]
Type: object
Custom settings
Show Source
Nested Schema : autoRestart
Type: object
Control how the ER process is restarted by the Administration Server if it terminates
Default Value: { "enabled":false, "onSuccess":false, "delay":"0", "retries":"9", "window":"60", "disableOnFailure":true }
Show Source
  • Allowed Values: [ "ogg:taskRestart" ]
  • Minimum Value: 0
    Maximum Value: 3600
    Default Value: 0
    The amount of time, in seconds, to pause between discovering that a process has terminated abnormally and restarting the process.
  • Default Value: true
    If true, the task is disabled when it fails all execution attempts in an execution window.
  • Default Value: false
    If set, the task can be restarted if it terminates.
  • Minimum Value: 0
    Maximum Value: 3600
    The number of times the task failed in the current window.
  • Default Value: false
    If false, the task is only restarted if it fails.
  • Minimum Value: 0
    Maximum Value: 3600
    Default Value: 9
    The maximum number of times the task should be restarted before aborting retry efforts.
  • Minimum Value: 0
    Maximum Value: 604800
    Default Value: 60
    The window of time, in seconds, during which retries are counted.
Nested Schema : autoStart
Type: object
Description of how the ER process starts with Administration Server
Show Source
  • Minimum Value: 0
    Maximum Value: 3600
    Default Value: 0
    Time to wait in seconds before starting process
  • Default Value: false
    If set, the process is started when Administration Server starts
Nested Schema : miningCredentials-x-oneOf[0]
Type: object
Show Source
  • Allowed Values: [ "ogg:credentialsRef" ]
  • Minimum Length: 1
    Maximum Length: 30
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
  • Minimum Length: 1
    Maximum Length: 30
    Default Value: OracleGoldenGate
    Pattern: ^[a-zA-Z][a-zA-Z0-9_#$]*$
Nested Schema : registration-x-oneOf[0]
Match One
Show Source
Nested Schema : registration-x-oneOf[0]-x-oneOf[0]
Type: object
Integrated extract registration options
Show Source
Match Any
Show Source
Nested Schema : containers
Type: array
Minimum Number of Items: 0
Maximum Number of Items: 256
Show Source
Nested Schema : csn
Match One
Show Source
  • Minimum Value: 0
    Maximum Value: 9223372036854776000
    System Change Number(Normal Format) for Oracle Database.
    Example: 6488359
  • Minimum Length: 3
    Maximum Length: 64
    Pattern: [0-9]+[.][0-9]+
    System Change Number(Alternate Format) for Oracle Database.
    Example: 6488359.3456712
Nested Schema : share
Describe how to share the LogMiner data dictionary
Default Value: false
Match One
Show Source
  • Minimum Length: 1
    Maximum Length: 8
    Pattern: ^[A-Z_$][A-Z0-9_$]*$
Nested Schema : items
Match One
Show Source
  • Minimum Length: 1
    Maximum Length: 130
    Pattern: ^([^.*?"]{1,128}|["].{1,128}["])$
Nested Schema : source-x-oneOf[2]
Type: object
OGG 19c Syntax NO LONGER SUPPORTED
Show Source
Nested Schema : items
Match One
Show Source
Nested Schema : items-x-oneOf[0]
Type: object
Show Source
  • Allowed Values: [ "ogg:trail" ]
  • Minimum Length: 1
    Maximum Length: 4095
    Description for the trail
  • Minimum Length: 2
    Maximum Length: 2
    Pattern: ^[A-Za-z][A-Za-z0-9]$
    The two-character name of the trail
  • Minimum Value: 0
    Maximum Value: 2147483647
    Offset in trail sequence file
  • Minimum Length: 1
    Maximum Length: 4096
    The path where trail data is stored
  • processRef
    Minimum Number of Items: 1
    Maximum Number of Items: 5000
    List of all processes associated with this trail
  • Default Value: false
    Indicates if trail is local or remote
  • Minimum Value: 0
    Maximum Value: 999999999
    Default Value: 0
    Trail beginning sequence number
  • sequenceLastArchived
    Minimum Number of Items: 1
    Maximum Number of Items: 128
    Last sequence number archived (Managed Trails only)
  • Default Value: 9
    Allowed Values: [ "6", "9" ]
    Number of digits in sequence file name
  • Default Value: false
    Indicates sequence number length will change
  • Minimum Value: 0
    Maximum Value: 999999999
    Default Value: 0
    Maximum trail sequence number that exists in the deployment
  • Minimum Value: 0
    Maximum Value: 999999999
    Default Value: 0
    Maximum trail sequence number in use
  • Minimum Value: 0
    Maximum Value: 999999999
    Default Value: 0
    Minimum trail sequence number that exists in the deployment
  • Minimum Value: 0
    Maximum Value: 999999999
    Default Value: 0
    Minimum trail sequence number in use
  • Minimum Value: 1
    Maximum Value: 2000
    Default Value: 500
    The maximum size, in megabytes, of a file in the trail.
  • Minimum Value: 0
    Maximum Value: 18446744073709552000
    Bytes consumed by all trail sequences
  • Minimum Length: 3
    Maximum Length: 512
    Pattern: ^[a-zA-Z0-9_#$/-]*$
    The optional 'user-friendly' name for the trail
Nested Schema : processRef
Type: array
Minimum Number of Items: 1
Maximum Number of Items: 5000
List of all processes associated with this trail
Show Source
Nested Schema : sequenceLastArchived
Type: array
Minimum Number of Items: 1
Maximum Number of Items: 128
Last sequence number archived (Managed Trails only)
Show Source
Nested Schema : items
Type: object
A reference to an OGG process associated with this managed trail
Show Source
Nested Schema : processName
Match Any
Show Source
  • Minimum Length: 1
    Maximum Length: 8
    Pattern: ^[A-Z_$][A-Z0-9_$]*$
  • Minimum Length: 1
    Maximum Length: 32
    Pattern: ^[A-Za-z][A-Za-z0-9-_.]*$
Nested Schema : items
Type: object
Show Source
Nested Schema : archiveTarget
The location where the trail sequences were archived
Match One
Show Source
Nested Schema : archiveTarget-x-oneOf[1]
Type: object
OCI Object Storage Bucket
Show Source
Nested Schema : archiveTarget-x-oneOf[2]
Type: object
S3-compatible object storage bucket
Show Source
Nested Schema : authentication
Match One
Show Source
Nested Schema : authentication-x-oneOf[0]
Type: object
Authentication using a named profile from the default profile configuration file
Show Source
Nested Schema : authentication-x-oneOf[1]
Type: object
Authentication for OCI using an instance principal
Show Source
Nested Schema : authentication-x-oneOf[2]
Type: object
Authentication for OCI using an API signing key for a user
Show Source
Nested Schema : authentication
Match One
Show Source
Nested Schema : authentication-x-oneOf[0]
Type: object
Authentication using a named profile from the default profile configuration file
Show Source
Nested Schema : authentication-x-oneOf[1]
Type: object
S3 Authentication using secrets
Show Source
Example Request (application/json)
{
    "description":"Region North",
    "config":[
        "EXTRACT extn",
        "EXTTRAIL north/ea",
        "USERIDALIAS ggnorth",
        "SOURCECATALOG dbnorth_pdb1",
        "TABLE hr.*;"
    ],
    "source":"tranlogs",
    "credentials":{
        "alias":"ggnorth"
    },
    "registration":{
        "optimized":false,
        "containers":[
            "dbnorth_pdb1"
        ],
        "replace":true
    },
    "begin":"now",
    "targets":[
        {
            "name":"ea",
            "path":"north/"
        }
    ]
}
Back to Top

Response

Supported Media Types

201 Response

The extract process was created successfully.

Body ()
Root Schema : RESTful API Standard Response
Type: object
Title: RESTful API Standard Response
Standard Response for all Oracle GoldenGate RESTful API calls
Show Source
Nested Schema : messages
Type: array
Minimum Number of Items: 0
Maximum Number of Items: 65535
Oracle GoldenGate messages issued during the request
Show Source
Nested Schema : response
Type: object
Oracle GoldenGate document from the request
Nested Schema : items
Type: object
Show Source
  • Allowed Values: [ "ogg:message" ]
  • Minimum Length: 9
    Maximum Length: 9
    Pattern: ^OGG[-][0-9]{5}$
    The Oracle GoldenGate message code
  • Minimum Length: 20
    Maximum Length: 32
    Pattern: ^[0-9]{4}[-](0[1-9]|1[0-2])[-](0[1-9]|[12][0-9]|3[01])[tT ]([01][0-9]|2[0-3]):[0-5][0-9]:([0-5][0-9]|60)([.][0-9]{1,6})?([zZ]|[+-][0-9][0-9]:[0-5][0-9])$
    The date and time that the message was issued
  • Allowed Values: [ "INFO", "WARNING", "ERROR" ]
    The severity of the message
  • Minimum Length: 1
    Maximum Length: 4095
    A human-readable description that provides information and detail specific to this occurence of the information, warning or error.
  • Minimum Length: 2
    Maximum Length: 4095
    Pattern: ^[a-zA-Z][a-zA-Z0-9+-.]*:[^ \t]*$
    An absolute URI [RFC3986] to a page that describes the info, warning or error type.
Example Response (application/json)
{
    "$schema":"api:standardResponse",
    "links":[
        {
            "href":"http://localhost:9012/services/v2/extracts/EXTN",
            "mediaType":"application/json",
            "rel":"canonical"
        },
        {
            "href":"http://localhost:9012/services/v2/extracts/EXTN",
            "mediaType":"application/json",
            "rel":"self"
        }
    ],
    "messages":[
        {
            "$schema":"ogg:message",
            "code":"OGG-08100",
            "issued":"2024-04-03T22:33:44Z",
            "severity":"INFO",
            "title":"Integrated Extract added.",
            "type":"https://docs.oracle.com/en/middleware/goldengate/core/23.4/error-messages/"
        },
        {
            "$schema":"ogg:message",
            "code":"OGG-02003",
            "issued":"2024-04-03T22:33:51Z",
            "severity":"INFO",
            "title":"Extract group EXTN successfully registered with database at SCN 2065052.",
            "type":"https://docs.oracle.com/en/middleware/goldengate/core/23.4/error-messages/"
        },
        {
            "$schema":"ogg:message",
            "code":"OGG-10183",
            "issued":"2024-04-03T22:33:51Z",
            "severity":"INFO",
            "title":"Parameter file EXTN.prm passed validity check.",
            "type":"https://docs.oracle.com/en/middleware/goldengate/core/23.4/error-messages/"
        },
        {
            "$schema":"ogg:message",
            "code":"OGG-08100",
            "issued":"2024-04-03T22:33:51Z",
            "severity":"INFO",
            "title":"EXTTRAIL added.",
            "type":"https://docs.oracle.com/en/middleware/goldengate/core/23.4/error-messages/"
        }
    ]
}
Back to Top