Introduction-介绍

The present article purpose is to introduce DeMeter Tightening Results API, its usage and purpose.

当前的文档是介绍Demeter的拧紧数据API的用法和目的


TABLE OF CONTENTS

Introduction介绍

1 - Pre- requisites先决条件  

2 - DeMeter Tightening API  

     2.1 - API: definition, purpose and overviewAPI定义，目的和总览 

     2.2 - Working with DeMeter API使用API  

          2.2.1 - API V1 Connection StringV1版本的连接字段

          2.2.2 - API V2 Connection stringV2版本的连接字段   

          2.2.3 - API Tightening Data: an overviewAPI反馈的数据：总览  

3 - Further reading


1 - Pre- requisites

1-先决条件  

We advise you to read through the following articles before diving in:

我们建议再阅读此文档前先了解以下文档


2 - DeMeter Tightening API  

2.1 - API: definition, purpose and overview

2.1-API：定义，目的，总览 

API stands for Application Programming Interface.

It is a software intermediary allowing two application to exchange information or "talk" to each other without having to know how either one works. An API is therefore often the preferred solution to simplify connectivity between several systems.


The specific benefits of using DeMeter provided API to retrieve tightening data rather than relying on database queries are:

  • Database scheme change: the API will remain stable over the versions, regardless of any changes brought to the database by new features (additional data - change to the data string...).
  • Performances: the risk of performance slow-down is lowered by retrieving data via the API rather than by querying the DeMeter database.

Developing a software to retrieve tightening data via the API will therefore have the benefits of a lower maintenance when compared to database queries (since the later may need adjustment from version to version).


Early version of the DeMeter tightening results API lets you retrieve only the tightening results associated to a specific VIN: this is DeMeter Open AI V1.


DeMeter Open AI V2 extends the range of retrieved Tightening Results: all results (up to 1000) within a time frame can be retrieved.


Note: API documentation is embedded in DeMeter. It can be accessed via the connection string http(s)://127.0.0.1:(portNumber)/api-docs/index.html?urls.primaryName=DeMeter%20Open%20API.

API代表应用程序编程接口。

它是一种软件中介，允许两个应用程序交换信息或相互“对话”，而无需了解其中任何一个的工作原理。因此，API通常是简化多个系统之间连接的首选解决方案。

使用DeMeter提供的API来检索拧紧数据，而非依赖数据库查询，其具体优势如下：

数据库方案变更：无论新功能给数据库带来何种变化（如增加数据、更改数据字符串等），API在各版本间将保持稳定。

性能：通过API检索数据而非查询DeMeter数据库，可降低性能下降的风险。

因此，与数据库查询相比，开发一款通过API检索拧紧数据的软件将具有维护成本更低的优势（因为数据库查询可能需要在不同版本之间进行调整）。

DeMeter拧紧结果API的早期版本仅允许您检索与特定VIN相关的拧紧结果：这是DeMeter Open AI V1。

DeMeter Open AI V2扩展了检索到的拧紧结果的范围：可以检索到某一时间范围内的所有结果（最多1000个）。

注意：API文档已嵌入DeMeter中。可通过连接字符串进行访问 http(s)://127.0.0.1:(portNumber)/api-docs/index.html?urls.primaryName=DeMeter%20Open%20API. 

2.2 - Working with DeMeter API  


2.2.1 - API V1 Connection String  

The DeMeter API can be accessed via the following connection string:

http://DeMeter_IP:DeMeter_Port/getdata/v1/tighteningresults?vin=123456&includeCurve=false&includeSteps=false, where:

  • DeMeter_IP is the IP address of your server.
  • DeMeter_Port is your DeMeter server API port number. Refer to DeMeter installation procedure for additional details about DeMeter port configuration.
  • Vin lets you provide the identifier for the tightening result(s) you wish to retrieve.
  • IncludeCurve: set to false by default. Setting the value to true will let you retrieve the numerical values for each point of the target result(s) stored curves.
  • IncludeSteps: set to false by default. Setting the value to true will let you retrieve the numerical result for each step within a specific tightening strategy, rather than only the end result.


Note: ensure the connection string references the secured port if your DeMeter server uses a certificate. In such a case, you will need to replace http by https in the connection string.


The aforementioned string can be used in any web browser to display the tightening results for tests purpose.

可以通过以下连接字符串访问DeMeter API：

http://DeMeter_IP:DeMeter_Port/getdata/v1/tighteningresults?vin=123456&includeCurve=false&includeSteps=false，其中：

DeMeter_IP是您服务器的IP地址。

DeMeter_Port 是您的 DeMeter 服务器 API 端口号。有关 DeMeter 端口配置的更多详细信息，请参阅 DeMeter 安装程序。

Vin允许您提供希望检索的拧紧结果的标识符。

IncludeCurve：默认设置为false。将该值设置为true将允许您检索存储的曲线中每个目标结果点的数值。

IncludeSteps：默认设置为false。将该值设置为true，您将能够获取特定拧紧策略中每一步的数值结果，而不仅仅是最终结果。

注意：若您的DeMeter服务器使用了证书，请确保连接字符串指向的是安全端口。在这种情况下，您需要在连接字符串中将http替换为https。

上述字符串可在任何网络浏览器中使用，以展示测试中的紧固结果。

Note: while the connection string can be used with any browser, Firefox wraps the data for a better rendering. Therefore, if Firefox is among the browser allowed by your IT, we advise you to favour it.

注意：虽然该连接字符串适用于任何浏览器，但Firefox能更好地包装数据以实现更佳的呈现效果。因此，如果您的IT部门允许使用Firefox，我们建议您优先选择该浏览器。


2.2.2 - API V2 Connection string  

It is now mandatory to define a Time Frame for the data you wish to retrieve. To set it up, the following parameters are necessary:

  • A startTime: all records taken after the provided value will be considered for retrieval.
  • An endTIme: the last retrieved entry must have been recorded before this date.
  • A dateMode: this setting can either be set to:
    - controller: it is the date time of the issuer of the record that will be taken into account for the filtering.
    - demeter: it is the date time at which DeMeter has received the record.

This version of the API requires, in addition to a time frame, at least one of the following parameter:

现在，必须为您希望检索的数据定义一个时间范围。要设置时间范围，需要以下参数：

开始时间：所有在给定值之后获取的记录都将被考虑用于检索。

结束时间：最后检索到的条目必须在此日期之前记录。

日期模式：此设置可设置为：

- 控制器：在进行筛选时，将考虑记录发布者的日期时间。

- demeter：这是DeMeter接收记录的日期时间。

此版本的API除了需要时间范围外，还需要以下至少一个参数：

  • A VIN.  Lets take the example of identifier VIN_Example. The request URL would be:
https://127.0.0.1:4551/getdata/v2/tighteningresults?startTime=2023-07-21T22%3A00%3A00.000%2B01%3A00&endTime=2024-04-22T22%3A00%3A00.000%2B01%3A00&dateMode=controller&vin=VIN_Example&includeCurve=false&includeSteps=false
  • A Controller Name. Lets take the example of a controller named CPS_CVI3_Controller. The  request URL would be:

https://127.0.0.1:4551/getdata/v2/tighteningresults?startTime=2023-07-21T22%3A00%3A00.000%2B01%3A00&endTime=2024-04-22T22%3A00%3A00.000%2B01%3A00&dateMode=controller&controllerName=CPS_CVI3_Controller&includeCurve=false&includeSteps=false

  • A Controller Serial Number. Lets take the example of a controller with serial number 46262000436. The request URL would be:

https://127.0.0.1:4551/getdata/v2/tighteningresults?startTime=2023-07-21T22%3A00%3A00.000%2B01%3A00&endTime=2024-04-22T22%3A00%3A00.000%2B01%3A00&dateMode=controller&controllerSerialNumber=46262000436&includeCurve=false&includeSteps=false

  • A Tightening Unit Name. Lets take the example of a Tightening Unit named CPS_TU. The request URL would be:

https://127.0.0.1:4551/getdata/v2/tighteningresults?startTime=2023-07-21T22%3A00%3A00.000%2B01%3A00&endTime=2024-04-22T22%3A00%3A00.000%2B01%3A00&dateMode=controller&tighteningUnitName=CPS_TU&includeCurve=false&includeSteps=false

  • A Tightening Unit Number. Lets take the example of Tightening Unit number 53.

https://127.0.0.1:4551/getdata/v2/tighteningresults?startTime=2023-07-21T22%3A00%3A00.000%2B01%3A00&endTime=2024-04-22T22%3A00%3A00.000%2B01%3A00&dateMode=controller&tighteningUnitNumber=53&includeCurve=false&includeSteps=false


Note:

  • By default, output from a query to API V2 will be a single JSON formated answer limited to 1000 results.
  • It is possible to stream the query results by changing .../getdata/v2/... to .../getdata/v2-stream/... Each result will be JSON formated. Please note that this approach is more resource efficient, thus allowing for the retrieval of up to 10000 results.

注：

默认情况下，向API V2发出的查询请求的输出将是一个JSON格式的答案，且结果数量限制为1000条。

通过将.../getdata/v2/...更改为.../getdata/v2-stream/...，可以以流式传输查询结果。每个结果将以JSON格式呈现。请注意，这种方法资源效率更高，因此最多可以检索10000个结果。

2.2.3 - API Tightening Data: an overview  

The API will provide you all the tightening results sharing the same VIN  in a single response.

API将通过一次响应，为您提供共享同一VIN的所有拧紧结果。

Firefox use case:

The snapshot below shows you an example where the VIN is associated to 6 tightening results (all associated to a single Assembly Process).

Firefox使用场景：

下面的截图展示了一个示例，其中车辆识别码（VIN）与6个拧紧结果相关联（所有结果均与单个装配过程相关联）。

A specific result can be accessed to retrieve the information for a specific tightening.

可以访问特定结果来检索特定拧紧操作的信息。


Results' data are grouped by category that you can expand. The below snapshot shows you how to access final angle, final torque an report:

结果数据按类别分组，您可以展开查看。下面的截图展示了如何访问最终角度、最终扭矩和报告：


Note: keep in mind that the example above is just for discovery purpose of the existing API fields. The real value of the feature is that it can be accessed by developing a software capable of extracting all the required data.

注意：请记住，上述示例仅用于发现现有API字段。该功能的真正价值在于，可以通过开发一款能够提取所有所需数据的软件来访问它。

Feel free to contact your remote support team if you feel you need additional information about this feature.


3 - Further reading

3 - 进一步阅读  

The following articles provides you with further details about tightening results Enum Fields :  

以下文章为您提供了关于紧固结果枚举字段的更多详细信息：