WITSML 1.4.1接口：实时石油业数据交换标准

4星 · 超过85%的资源需积分: 48 138 浏览量更新于2024-07-20 3 收藏 1.1MB PDF 举报

WITSML 1.4.1接口规范是一个针对石油行业的标准接口，全称为Wellsite Information Transfer Standard Markup Language (井场信息传递标准标记语言)。这个由石油技术开放标准协会(POSC)制定的协议，旨在实现井场服务提供商与石油公司之间实时、无缝的数据交换，从而加速信息流通并提升决策效率。它是在全球化石油和天然气产业背景下，为了共享现场操作模式而迈出的重要一步。 WITSML 1.4.1版本的应用程序编程接口（API）设计，文档类型为正式规格，重点关注数据对象定义和Web服务规格，目的是确保服务公司和运营商之间的信息流畅。API组件包括客户端/服务器的网络服务接口，使得通过应用程序软件进行数据交换成为可能，无论是办公室内部还是跨公司都能实现高效的数据传输。该规范在2014年7月由Energistics和WITSML Special Interest Group（SIG）共同发布，文档版本为DOC1.4.1-v3。文档包含了详细的开发过程，遵循了Energistics的标准化流程，强调开放性和共识构建，以确保内容的一致性和标准化。文档中明确指出了关键词，如标准、能源、钻探、Web服务等，表明WITSML 1.4.1 API适用于这些领域，并且强调其在保护知识产权和版权方面的使用规定。该规范的颜色标识（R:210, G:124, B:50）可能是为了在视觉上区分文档，便于用户识别。总结来说，WITSML 1.4.1接口规范是一个关键的技术标准，它促进了石油行业内的数据标准化和通信效率，对于提升作业现场的协同工作以及远程决策支持具有重要意义。对于任何参与石油开采或相关服务的组织而言，理解和掌握这一API都是实现数字化转型和优化业务流程的关键要素。

WITSML STORE Application Program Interface (API) v1.4.1

Document Version: DOC1.4.1-v3/July 2014 Page 16

The natural key for a node is the combination of all natural identifiers in the hierarchy down to and

including that node. While natural keys MAY be non-unique within the context of a server, every effort

SHOULD be made to insure their uniqueness to eliminate ambiguity.

When the natural keys are not unique, then human inspection is needed to determine if the nodes

represent:

• Same thing (i.e., if the information in the nodes SHOULD be combined) or

• Different things (i.e., their identity SHOULD be changed).

2.3 WITSML Document

Consistent with the way the XML literature uses the word "document," the term does not necessarily

mean a physical file. A text string of XML being sent using an HTTP/S POST is also an XML document. If

that XML represents one or more WITSML data-objects, it is then a WITSML document.

A WITSML document is one or more complete WITSML data-objects—such as well, wellbore or log—

represented as an XML document, which is essentially a text string. That is, each WITSML data-object is

defined by an XML schema and is its own document. Because each data-object carries with it its own

identifier (UID) and the identifier(s) of its parent, grand-parent, etc., data items in one well or wellbore can

be transported as one XML document (which again, is simply a text string).

So the data-objects can be logically thought of as being in one tree or hierarchy, but they are physically

represented as separate documents. In Figure 2, page 13, that well and all of its child data-objects would

be represented as thirteen WITSML documents, one for each data-object.

WITSML STORE Application Program Interface (API) v1.4.1

Document Version: DOC1.4.1-v3/July 2014 Page 17

3. STORE Interface Overview

The WITSML API, named the STORE Interface, specifies a standardized way of electronically

transporting WITSML data-objects between systems using the HTTP/S protocols—which includes HTTP

(unencrypted) and HTTPS (encrypted), referred to collectively as HTTP/S.

The STORE Interface is platform independent and conforms to SOAP version 1.1.

The STORE Interface provides client applications the ability to interact with WITSML servers to:

• Add WITSML a data-object to a server.

• Update an existing WITSML data-object on a server.

• Delete an existing WITSML data-object (or a subset) on a server.

• Get (query) one or more existing WITSML data-objects from a server.

3.1 Client/Server Approach

A standardized Web Services Description Language (WSDL) file (see 4.3, page 34) is used to define the

STORE Interface functions, which are exposed by SOAP. The function names (methods) are prefixed

with “WMLS_” (a contraction of WITSML and STORE). The WITSML data-objects are exchanged

between client and server as string values within XML documents.

3.1.1 Synchronous Transmission

When the client makes a request of a WITSML server, the server MUST respond immediately and

synchronously with an acknowledgement or error code.

3.1.2 Representation vs. Transport vs. Storage

WITSML defines an interoperability specification about how the data is represented and a standard way

of transporting the data electronically. It does not define the storage mechanism.

• Representation. WITSML data-objects being exchanged between systems are always represented

as XML documents. The data-object schemas define the format of these data-objects when they are

represented as XML documents.

• Transport. Because XML documents are simply text files, they can be transported by various means,

such as email or other file transfer method. A WITSML data-object could even be in the form of a

printed or faxed document.

This API document specifies a standardized way of electronically transporting WITSML data-objects

between systems using HTTP/S-based protocols. However, companies can send and receive

WITSML data streams without using the STORE Interface.

• Storage. While WITSML data-objects transported between systems are represented as XML

documents, the WITSML specification does not dictate how the WITSML data-objects are to be

stored within those systems, and the client application cannot assume any particular storage

mechanism. The data-objects might be stored as text files or in a database system.

3.2 Authentication and Encryption

The STORE interface uses HTTP/S Basic Authentication, as described in IETF RFC’s 2616 (HTTP 1.1)

and 2617 (Authentication).

The capabilities and implementation of authorization checking, if any, are not specified by WITSML. It is

up to participating companies to agree if authentication is needed to access a WITSML server. If it is

needed, the authentication data will be sent with each WITSML message.

Secure Sockets Layer (SSL) for HTTP (HTTPS) can be used to encrypt the HTTP traffic.

WITSML STORE Application Program Interface (API) v1.4.1

Document Version: DOC1.4.1-v3/July 2014 Page 18

3.3 Server Data Compression

Servers MUST support gzip HTTP compression for server response and the compression must be

compliant with IETF RFC 2616 (HTTP 1.1) Section 3.5 (Content Codings).

For client requests, some WITSML functions support alternate compression capabilities, which are

explained in the sections for those functions in Chapter 6, page 41.

3.4 Key API Components

Key components of the STORE Interface are listed and described here.

Component Description/Purpose

XML templates The STORE interface uses the concept of a template, which is a well-formed

XML document that specifies “by example” what WITSML data-objects and data

items within those data-objects are to be acted upon. Clients use templates in

the XMLin parameter of the various STORE interface functions.

For more information on templates, see Section 4.1, page 23.

WSDL file The WSDL file, which is sometimes called the API Signature, is a contract

between the provider system (server) and the consumer system (client) that

specifies how the Web service will interact in terms of what function calls are

available, their parameters, the protocols they run over and where the service is

located.

The file is created using the Web Services Description Language (WSDL), an

XML format for describing these types of network services.

For more information, see Section 4.3, page 34.

Capabilities Objects Special data-objects used by the STORE Interface to exchange information

about the capabilities of a client or a server. The client and server each has its

own Capabilities Object—capClient and capServer.

For more information, see Section 4.2, page 28.

Functions The basic tasks or functionality that can be performed with the STORE Interface

are contained in functions. The functions are developed using WSDL.

For more information, see Chapter 6, page 41.

3.4.1 Schema Variants

The following schemas represent generated variants of the normative data schemas. These schemas are

only normative when used within the context of a Web service. They are used to accommodate the

different requirements for mandatory data for the various actions (e.g., retrieve, add, update, and delete)

of the Web services. The object plural version attribute is required in all variants.

Schema Type Copies of the normative schema file with the following exceptions:

Read Schema All elements and attributes are optional and all choices have been eliminated. If used

within a WITSML Web service, these schema files must represent the XMLout response

from the WITSML WMLS_GetFromStore function (see Section 6.6, page 54).

Write Schema All uids and parentage-uids are mandatory (object-uids remain optional). If used within a

WITSML Web service, these schema files must represent the XMLin input to the

WITSML WMLS_AddToStore function (see Section 6.4, page 47).

Update Schema All elements and attributes are optional except that all unique identifier attributes and

uom attributes are mandatory. If used within a WITSML Web service, these schema files

must represent the XMLin input to the WITSML WMLS_UpdateInStore function (see

Section 6.6, page 54).

Delete Schema All elements and attributes are optional except for all object uids and parentage-pointers,

which are mandatory. If used within a WITSML Web service, these schema files must

represent the QueryIn input to the WITSML WMLS_DeleteFromStore function (see

Section 6.5, page 50).

WITSML STORE Application Program Interface (API) v1.4.1

Document Version: DOC1.4.1-v3/July 2014 Page 19

3.5 Versioning

The STORE has four major components that can be versioned, each using versioning in slightly different

contexts. The components and their corresponding version names are listed and summarized in the table

below. Sections below provide more details for each component.

Note that the version numbering of these components is mostly independent of one another. The version

numbers might increment at different rates and times for different parts of the WITSML specification.

Component Version Name/Description

Data-objects

Data Schema Version. The version of the XML data schema

against which the data-object can be validated.

For more information, see Section 3.5.1, page 19.

WSDL file

WSDL file version. The version of the WSDL file is specified by the

URI of the targetNamespace attribute of its <definitions> element.

Once defined, the WSDL file SHOULD NOT change, else consumer

applications that were written to an earlier specification might

"break."

For more information, see Section 3.5.2, page 20.

API Capabilities Describes the details about how the client/server interface operates.

Each time a client and server communicate, the capabilities version

is exchanged through special client and server Capabilities Objects.

Two versions are associated with API Capabilities:

API Version is specified in the WITSML STORE application

program interface (API) (this document). NOTE: The API

version and the version of the API document are NOT the

same thing. The API document can be updated (e.g., for

clarification or error correction) that does not change API

behavior.

In this case, the API document version is updated, but not the

API version. The API document version is found on page 2

and is formatted as “DOC1.4.1-v2”.

API Schema Version is the version of the schema that defines the

Capabilities Objects.

For more information, see section 3.5.3, page 20.

Executable programs (either client or

server applications)

The version of a particular implementation of all of the above.

The version of an executable program can be used to help in

troubleshooting. Each version may be coded to support only one

combination of the above components.

For more information, see section 3.5.5, page 22.

3.5.1 Data Schema Version

For a data-object, the Data Schema Version number specifies the version of the XML data schema

against which the data-object can be validated. The Data Schema Version is conveyed in the version

attribute of the data-object's root plural element:

</wells>

The example indicates that the well data-object is compliant with the WITSML 1.4.1.1 XML data schemas.

A client can determine the Data Schema Versions of WITSML data supported by the server using

WMLS_GetVersion function (see Section 6.2, page 44).

WITSML STORE Application Program Interface (API) v1.4.1

Document Version: DOC1.4.1-v3/July 2014 Page 20

3.5.1.1 Significance of the Four Digits

Each of the four digits signifies a level of change. This numbering scheme applies to data schemas, the

API, and API schemas.

• First digit. Represents a major structural or semantic change to all of the schemas as a whole. This

is the level at which namespace changes are made.

• Second digit. Represents breaking changes across schemas, changes that would cause a document

to have serialization or validation errors if read by a client or server at a previous revision in this digit.

• Third digit. Non-breaking additions to schemas only, which implies that only optional elements and

attributes can be added to schemas and that elements and attributes could be marked "deprecated",

but not removed from the schema.

− This is the minimum level of change that is required to make a release of the schema package to

the Energistics website.

− It is intended that entirely new high-level data-objects (object_ schemas) could be added between

major releases at the same version number of the current release (much like when the WITSML

stimJob data-object was released), provided that the new data-objects do not introduce any

breaking changes to included low-level schema components.

• Fourth digit. Changes in the XML files of standard enumerations and reference data. These

documents would continue to validate at an XML level, but might encounter errors if presenting

enumeration values that were unknown to the corresponding client or server.

3.5.2 WSDL File Version

The WSDL file, which is sometimes called the API Signature, is a contract between the provider system

(server) and the consumer system (client) that specifies how the Web service will interact in terms of what

function calls are available, their parameters, the protocols they run over, and where the service is

located.

Once the WSDL is defined, it SHOULD NOT change, else consumer applications that were written to an

earlier specification might "break." For more information on the WSDL file, see Section 4.3, page 34.

When new functionality needs to be added, the WSDL file can be updated but ideally in a way that

extends but does not break existing functionality. Or if the changes are such that it is not possible to

provide backward compatibility to existing clients, a completely new WSDL file (with a different Web

service name) can be published.

The version of the WSDL file is specified by the URI of the targetNamespace attribute of its <definitions>

element:

<definitions name="WMLS" targetNamespace="http://www.witsml.org/wsdl/120" …

A <documentation> element in the WSDL file also specifies the version in a more easily readable form:

<documentation>WITSML Version 1.2.0 STORE interface WSDL file </documentation>

Client programs SHOULD use the targetNamespace URI rather than the <documentation> element to

determine the version of the WSDL file.

3.5.3 API Capabilities: API Version and API Schema Version

The API capabilities describe the "details" about how the client/server interface operates. An API's

capabilities further define and clarify the basic functionality that the WSDL file advertises (think of the

capabilities as being the "fine print" on the contract). For example, while the WSDL file says that a client

can issue a WMLS_GetFromStore function call to retrieve WITSML data-objects from a server, it is the

API's capabilities that determine which data-objects are available on a particular server.

The API capabilities version is referred to as the API Version.

剩余158页未读，继续阅读

ibo1047

粉丝: 1
资源: 1

WITSML 1.4.1接口：实时石油业数据交换标准

WITS 数据交换转换器 WITSHUB

WITSML_v1.4.0_API

witsmllib:C＃中的Witsml客户端库

witsml 1.4.1.zip

WITSML代码

witsml-explorer:Witsml Explorer数据管理工具

java witsml 客户端 源码

witsml:PDS WITSMLstudio核心库

witsml-studio:PDS WITSMLstudio桌面

docker-wmls:Witsml客户端Docker文件

最新资源

java witsml 客户端源码