API 简介及使用说明

作为提供在线流体云计算的服务商，本集团致力于简化用户获取相关工程软件的途径，方便计算结果的输入和输出。基于此理念，最近我们开发了向用户提供工程计算的第二种途径，网络API 接口。使用API接口，用户可以根据自身的需求，将我们的计算功能整合进自行开发的桌面软件、移动端Apps，甚至是用户的网站中，完成所需要的运算。

比如，在SCADA（Supervisory Control and Data Acquisition, 监控和数据采集）系统中，用户需要实时获取管道中流体的组成及温度压力，计算流体的物性和相态，以作必要的生产操作上的调整。传统软件对此无法满足，必须设计一款定制软件。而使用我们开发的网络API，可让用户把我们的计算模型快捷无缝地集成到其系统中去，达到事半功倍的效果。

如何使用API?

请用户遵循以下步骤使用本站提供的网络 API：

  1. 用户注册并登录，点击右上角用户名下的“My Account”，点击“API Keys”。
  2. 在此界面中，上半部分是用户的API Key列表，您可点击“Create API”生成一个API Key，现在每位用户只允许生成一个。如果您的API Key已经达到规定的数量，此按钮将成灰色，表示不可用；此界面的下半部分是您的API Key使用记录。
  3. 您可在API Key列表中删除自己创建的Key，删除后可重新生成新的API Key。
  4. 创建API Key以后，您就可以在自己的程序中使用，请参见下方的案例程序了解使用方法。
  5. 每个API Key默认有一定的使用限制，暂时规定每个Key每天计算20次，如果您需要更多运算，请与我们联系。
  6. 使用API计算时，为了简化用户的数据结构，计算的选项与在网页中的计算会略有不同。
  7. 使用API计算时，输入与输出的数值单位使用网站的基准单位，组成使用摩尔百分比。您可以点击主菜单中的“在线计算”->“单位换算与定制”或 https://www.fluidmodelinggroup.com/Tools/fmgUnits 查看各类数值的基准单位。
  8. 用户可使用本网站系统中已经定义的组分进行运算，如果用户需要在运算中采用自己定义的组分与参数，请与我们联系。
  9. 目前，对用户开放相包线（包括等容线和临界烃露点）和PT闪蒸2项功能，其他功能的API正在开发中。

API描述:

API的调用地址为 https://www.fluidmodelinggroup.com/api；方式为POST；编码为UTF-8；数据必须以JSON格式上传；各项目名称应均为大写，说明如下：

  • API_KEY：必填项，字符串，即您在“My Account”中生成的API Key。此项缺失或无效将无法进行任何API调用。
  • COMMAND: 必填项，向网站请求的功能，现在有2个选项：
    • “help”：帮助信息
    • “calc”：进行计算
  • MODULE：必填项，字符串，进行计算的模块，仅当COMMAND=CALC时有效，目前，对用户开放2个模块：
    • “phaseenvelope”：相包线、等容线、临界烃露点的计算
    • “ptflash”：PT两相闪蒸计算
  • COMPONENTS：必填项，字符串数组，指定计算的物质组分名称，请注意不同模块的可选组分有不同，可以进入模块计算的网页中查看可用组分。如果物质组成带有拟组分，则运算前将进行特征化。
  • COMPOSITION：必填项，浮点数数组，指定计算的各物质的摩尔组成。
  • CONFIG：选填项，基本计算方法选项，如果不指定，则使用默认选项，成员有：
    • EOS：状态方程的选择，备选项有：
      • PR78: Peng-Robinson 1978 方法（默认）
      • PR76: Peng-Robinson 1976
      • PR90: Peng-Robinson (Magoulas & Tassios Revision) 1990
      • SRK: Soave-Redlich-Kwong 1972
      • ALS: Adachi-Lu-Sugie 1983
      • PT: Patel-Teja 1982
      • VPT: Valderrama-Patel-Teja 1990
      • SW: Schmidt-Wenzel 1980
      • YL: Yu-Lu, 1987
      • MDG: Modified Du-Guo 1989
      • TB: Trebble-Bishnoi 1987
      • SMTD: Salim Modified Trebble-Bishnoi 1994
    • VIS：粘度计算方法，备选项有：
      • 2REF: 2-Reference Corresponding States （默认）
      • 1REF: 1- Reference Corresponding States
      • LBC: Lohrenz-Bray-Clark
      • PREOS: Peng-Robinson EoS method
  • CHARACTERIZATION：选填项，物质含有拟组分时，如果未指定此项，则按照默认配置进行特征化计算，用户也可指定以下方法：
    • DISTRIB_FUNC：特征化方法，备选项有：
      • PED：Pedersen 1988方法（默认）
      • WHIT：Whitson 1988方法
      • MODPED：改进Pedsen 2001方法
    • PROP_CORR：关联式选项，备选项有：
      • PED：Pedersen 1988 （默认）
      • RDT：Riazi-Daubert(1980)-Thomasen(1986)
      • LK：Lee-Kesler(1976)
      • CE：Cavett(1964)-Edminstor(1958)
      • LKE：Lee-Kesler(1976)-Edminstor(1958)
      • TLK：Twu(1984)-Lee-Kesler(1976)
      • WSD：Winn(1957)-Sim-Daubert(1980)
      • RAS95：Riazi-Al-Sahhaf(1995)
      • RAS98：Riazi-Al-Sahhaf(1998)
    • PSEUDO_LUMP：拟组分归并方式选择，备选项有：
      • MASS：重量均分 （默认）
      • MOLE：摩尔均分
      • GAUSS：高斯分布
      • EQUAL：等值分布
    • PSEUDO_COUNT：整数，拟组分个数，默认值为5
    • PLUS_MW：浮点数，拟组分分子量，可选
    • PLUS_DENS：浮点数，拟组分密度，可选
  • PARAM：可变项目。PARAM是计算的参数，根据不同的计算模块，其内容有不同的结构，具体见下方解释：
    • 在phaseenvelope计算中，PARAM为可选项，如果没有PARAM，则仅计算输入数据的相包线；如果有PARAM，则其中必须带有“QUALITYLINE_GAS_FRAC”，该项为浮点数组，数值含义为等容线条件的气体比例，数值应在0－100之间，最多计算9条等容线。
    • 在ptflash计算中，PARAM为必填项，需要包括“PT_PAIR”项目，该项目为压力与温度对的数组，格式为：[{"P":60, "T":400}，{“P”:80,”T”:450}]，表示需要计算压力=60bar，温度=400K时，以及压力=80bar，温度=450K时两个点的闪蒸。可接受多达9对PT点闪蒸计算。

API 结果:

计算结果将以JSON格式返回，主要分为3个部分：

  • “status”：告知计算结果是否成功，“SUCCESS”或“FAILED”
  • “message”：返回信息，如果成功，将含计算耗时、计算时间；如果失败，将包含失败原因
  • “result”：计算结果，此项目根据不同计算模块将有不同的结构。

如果计算过程中发生严重错误，结果可能只返回字符串“Calling FMG API Calculation error. ”

示例代码

这里以Python和C#这两种语言为例：

Python:


import json,urllib.request
httpClient = None
try:
    data = {"API_KEY" : "B9E96302C25A40C49491C3BF......39D060D4D9C2B44ABEB405A93197AF8866", #Your API Key
    "COMMAND":"calc", #"help", #
    "MODULE":"phaseenvelope", #"ptflash", #
    "CONFIG":{
        "EOS":"PR76"
    },
    "COMPONENTS":['C1','C2','C3','C7+'], 
    "COMPOSITION":[0.2,0.5,0.1,0.2],
    #"CHARACTERIZATION":{
    #   "DISTRIB_FUNC":"MODPED",
    #   "PROP_CORR": "RDT",
    #   "PLUS_MW": 200,
    #   "PLUS_DENS": 0.95,
    #   "PSEUDO_LUMP": "mole",
    #   "PSEUDO_COUNT": 3
    #}
    #,"PARAM": {
    #   "QUALITYLINE_GAS_FRAC":[10,20,50]   #Quality line for phaseenvelope
    #   "PT_PAIR": [{"P":60, "T": 400}]
    #   }    
    }   
    para = json.dumps(data).encode('utf8')
    req=urllib.request.Request("https://www.fluidmodelinggroup.com/api", data=para, headers={'content-type': 'application/json'})   
    r=urllib.request.urlopen(req)   
    print(r.status)
    print(r.reason)
    txt = r.read()
    f=open('pythonResult.txt','wb')
    f.write(txt)
    f.close()
    print(txt)
except Exception(e):
    print(e)
finally:
    if httpClient:
        httpClient.close()

C#:


using Newtonsoft.Json;
using System.Net;
…

string apiurl = "https://www.fluidmodelinggroup.com/api";
var httpWebRequest = (HttpWebRequest)WebRequest.Create(apiurl);
httpWebRequest.ContentType = "application/json; charset=utf-8";
httpWebRequest.Method = "POST";
httpWebRequest.Accept = "application/json; charset=utf-8";
using (var streamWriter = new StreamWriter(httpWebRequest.GetRequestStream()))
{
    string _data = JsonConvert.SerializeObject(new
    {
        API_KEY = "B9E96302C25A40C49491C3BF......39D060D4D9C2B44ABEB405A93197AF8866", //Your API Key
        COMMAND = "calc", //"help", //
        MODULE = "phaseenvelope", //"ptflash", //
        CONFIG = new
        {
            EOS = "PR90"
        },
        COMPONENTS = new[] { "C1", "C2", "C3", "C7+" },
        COMPOSITION = new[] { 0.2, 0.5, 0.1, 0.2 }, 
        CHARACTERIZATION = new {
            DISTRIB_FUNC = "MODPED",
            PROP_CORR = "RDT",
            PLUS_MW = 200,
            PLUS_DENS = 0.95,
            PSEUDO_LUMP = "mole",
            PSEUDO_COUNT = 3
        }
        ,PARAM = new {
            QUALITYLINE_GAS_FRAC = new[] { 10, 50 }  //Quality line for phaseenvelope
            //PT_PAIR = new[] { new { P = 60, T = 400 }, new { P = 80, T = 450 } }
            }
    });
    streamWriter.Write(_data);
    streamWriter.Flush();
    streamWriter.Close();
    var httpResponse = (HttpWebResponse)httpWebRequest.GetResponse();
    using (var streamReader = new StreamReader(httpResponse.GetResponseStream()))
    {
        string result = streamReader.ReadToEnd();
        textBox1.AppendText(result);
    }
}

注：现在API Key的申请功能仅在英文站点开通。