AI 助理
备案控制台
官方文档
输入文档关键字查找
首页 智能数据建设与治理 Dataphin 智能数据建设与治理Dataphin-独享模式（半托管版） 操作指南 数据服务 API市场与应用管理 调用API

调用API

更新时间：
产品详情
我的收藏

调用API即应用根据运行环境调用当前环境中的API，特殊的，Basic模式下即使运行环境是开发环境，读取的仍然为生产环境的数据。在为企业建立API生态场景中，您需要调用API进行二次开发或开放API给合作伙伴等，帮助企业实现数据的资产化和价值化。本文为您介绍如何调用API。

前提条件

API文档入口说明

  • 从市场进入API文档：单击顶部菜单栏的服务 > API市场，单击左侧列表的API页签，再单击目标API文档说明列下的API文档，进入API文档页面。该方式进入生产环境下的API文档，无论是否拥有权限，均支持查看并下载API文档。

  • 从应用管理进入API文档：仅API已授权应用且用户有应用的权限支持进入。单击顶部菜单栏服务 > 应用管理，在左侧导航栏选择服务管理 > 已授权API服务 > 单击目标API操作列下的查看，进入API文档页面。该方式进入开发环境下的API文档，支持切换环境且可以下载API文档。

API文档及调试页面顶部操作

  • 切换API：您可在页面左上角切换查看API，根据API的名称或ID模糊搜索API，支持搜索当前用户已加入服务项目下已发布的API。系统将为您推荐最近9条API。

  • 切换API运行环境：

    • API文档：仅从应用管理 > 已授权API服务页面进入的API文档，支持选择有权限环境（开发环境、生产环境）查看API文档。当运行环境为开发环境时，公共请求参数列表支持apiVersion参数。

    • 调试API：支持选择有权限环境（开发环境、生产环境）进行API调试。当运行环境为开发环境，则使用开发数据源进行调试；当运行环境为生产环境，则使用生产数据源进行调试。

      说明

      • 当运行环境为开发环境，组合API调用的子API基于Dev-Prod模式提交的API配置，使用开发环境数据源进行调试；基于Basic模式提交的API配置，使用生产环境数据源进行调试。

      • 当运行环境为生产环境，组合API调用的子API基于Dev-Prod模式或Basic模式提交的API配置，使用生产环境数据源进行调试。

  • 切换API版本：当运行环境为开发环境，调试API时，支持在页面右上角切换API版本。仅可选择已提交的版本（包括已发布版本）。

步骤一：查询并申请API

说明

需申请该API的所属应用权限才能使用该API。

  1. 在Dataphin首页的顶部菜单栏，选择服务 > API市场。

  2. 单击API页签，再单击目标API文档说明列下的API文档，进入API文档页面。该方式进入生产环境下的API文档。根据API是否发布路径有所差异，详情请参见API文档入口说明。

  3. 在API文档页面，查看API的基本信息、排序设置（仅服务单元API-向导模式支持）、业务请求参数列表、公共请求参数列表、关联行级权限列表、返回参数列表及JSON返回示例，是否符合您的业务场景。

    说明

    • 当API类型为直连数据源API、服务单元API或组合API且关联行级权限开启时可查看关联行级权限列表信息。

    • 当调用模式为异步调用时，不支持API数据缓存，可通过游标的方式增量获取数据，因此异步调用无需配置缓存和结果分页等配置，公共请求参数也不展示PageSize、PageStart信息。

  4. 确认当前API符合您业务场景的后，在API服务页面单击申请状态列下的立即申请，跳转至管理中心 > 权限管理 > 我的权限 > 数据服务权限页面申请API的权限，详情请参见申请API权限。

步骤二：调试API

完成API权限申请后，您可以调试该API是否可以正常使用。

说明

调试API时，输入参数字符长度不超过1000个；若直接调用API，则无字符长度限制。

  1. 单击顶部菜单栏应用管理。

  2. 在左侧导航栏选择服务管理 > 已授权API服务，在已授权API服务页面，单击目标API操作列下的调试，进入API调试页面。

  3. 在API调试页面，配置调试输入值。调试参数配置与测试API是否符合预期，详情请参见步骤一：测试API。

    在API调试页面的顶部可以查看域名，该域名仅用于内部测试，实际调用域名，请参见查看域名。

    在API调试页面的可选返回参数列表区域，可在右上方快捷切换已授权的应用。

步骤三：下载文档

您可以下载API文档分享给其他开发人员，提高使用灵活性。支持下载Word格式的文档，便于修改；也可以下载为OpenAPI规范的YAML文档，用于阿里云百炼大模型的插件注册。

下载OpenAPI YAML文件

  1. 在Dataphin首页，单击顶部菜单栏的服务 > API市场。

  2. 单击左侧列表的API页签，选中目标API单击文档说明列下的API文档。

  3. 在API文档页面，单击右上角的下载OpenAPI YAML文件。

  4. 在下载OpenAPI YAML文件的对话框中，配置参数。

    参数

    描述

    格式

    支持阿里云百炼大模型平台、OpenAPI规范2种格式下载文件。

    operationID

    接口操作ID，用于接口操作的唯一标识。仅支持输入英文、下划线（_），不超过200个字符。

    summary

    接口描述。支持输入不超过200个字符。

    代码预览

    设置完成后，即可实时预览代码（JSON格式）。代码中各参数释义请参见OpenAPI 规范。

    openapi: 3.0.1
info:
  title: sq_test_mysql
  description: ""
  version: V1.4
servers:
- url: http://528fdcdcc62d4f4eb8f10ad99cdda9f3-cn-shanghai.alicloudapi.com
paths:
  /list/10172:
    post:
      summary: ""
      operationId: ""
      parameters:
      - name: appKey
        in: query
        description: 访问API所绑定的应用Key
        required: true
        schema:
          type: string
          example: "2000001"
      - name: env
        in: query
        description: API所在的环境
        required: true
        schema:
          type: string
          example: "prod:生产环境, pre:预发环境"
      requestBody:
        content:
          application/json:
            schema:
              required:
              - returnFields
              type: object
              properties:
                useModelCache:
                  type: boolean
                  description: "是否开启SQL翻译缓存, 有利于查询性能提升"
                  default: false
                pageStart:
                  type: integer
                  description: 分页查询的第几条开始
                  format: int32
                pageSize:
                  type: integer
                  description: 分页查询返回条数
                  format: int32
                returnFields:
                  type: array
                  items:
                    type: string
                    example: "[id, name, sexo]"
                conditions:
                  required:
                  - sex
                  type: object
                  properties:
                    namee:
                      type: string
                      example: null
                    sex:
                      type: string
                      example: null
                    idd:
                      type: string
                      example: null
                  description: 入参条件
                useResultCache:
                  type: boolean
                  description: "是否开启API查询结果的缓存, 有利于查询性能提升"
                  default: false
                orderBys:
                  type: array
                  description: 排序字段
                  items:
                    type: object
                    properties:
                      field:
                        type: string
                        description: 排序类型，枚举值(注意大写)，只有ASC或者DESC
                      order:
                        type: string
                        description: 排序类型，枚举值(注意大写)，只有ASC或者DESC
                        example: ASC或者DESC
        required: true

  5. 配置完成后，单击下载，将文件下载至本地。

下载API文档

  1. 在Dataphin首页，单击顶部菜单栏的服务 > API市场。

  2. 单击左侧列表的API页签，单击目标API文档说明列下的API文档。

  3. 在API文档页面，单击右上角的下载API文档，下载单个API文档；您也可以在API服务页面，选中多个API，单击底部的下载API文档，批量下载API文档。

    说明

    • 下载的API文档中会根据该API生成具体的调用示例，方便您使用；您也可以根据API调用模板配置调用示例。

    • 支持将API文档下载至本地，格式为Word。

    • API文档包括文档目录、文档版本、API调用示例、接口列表（按接口维度，每个接口内容包括基本信息、排序设置（仅服务单元API-向导模式支持）、业务请求参数列表、公共请求参数列表、关联行级权限列表（仅直连数据源API、服务单元API或组合API且关联行级权限开启时支持）、返回参数列表、JSON返回示例以及该API调用的具体示例）。

    • 当网络配置的API网关为阿里云API网关，公网二级域名/内网VPC域名开启且所有用户可见时，下载的API文档可查看正确的Host信息；若为内置网关，仅是否展示域名为是时，可查看正确的Host信息。

API调用模板

说明

仅超级管理员支持管理SDK及调用示例、编辑调用说明。

  1. 在数据服务页面，单击顶部菜单栏应用管理，再单击左侧导航栏的调用说明，进入调用说明页面。

  2. 在调用说明页面，单击API调用说明页签，进入API调用说明页面。

  3. 在API调用说明页面，查看API调用示例的模板，并可执行如下操作。

    • 默认调用示例下载：您可以单击默认调用示例下载，下载API调用示例，包括同步调用和异步调用。

    • python调用示例下载：如果需要通过Python方式调用API，则单击python调用示例下载，下载Python示例文件压缩包。

    • Java SDK下载：如果需要通过Java SDK方式调用API，则单击Java SDK下载，下载Java SDK代码包。

    • 管理SDK及调用示例：单击管理SDK及调用示例按钮，进入管理SDK及调用示例页面，您可以统一管理API调用示例，支持新增调用示例或对调用示例进行排序。

      • 新增：单击底部的新增按钮，添加调用示例。

        • 名称：输入调用示例的名称，将在API调用说明页面展示。名称唯一，建议输入不超过10个字符，最长不超过50个字符。

        • 说明：填写调用示例的简单描述，便于相关业务人员了解用途，最长不超过100个字符。

        • 上传文件：单击上传按钮，从本地选择文件上传至Dataphin。支持上传的文件格式为zip、rar、doc、docx、PDF、jpg且文件大小不超过200M。

          支持将文件下载至本地。

        • 是否展示：影响在API调用说明页面是否可见该调用示例。保存后，默认开启，支持关闭该调用示例。

        • 保存：支持保存修改或新增的调用示例。

        • 编辑/删除：支持修改或删除自定义添加的调用示例配置信息。

      • 排序：单击排序，拖动调用示例进行排序，单击右上角的完成按钮，完成排序。此处排序顺序将影响API调用说明页面的默认展示顺序。

        说明

        • 支持创建不超过10个API调用示例（包含系统默认提供的调用示例）。

        • 系统默认提供的调用示例不支持编辑、删除，支持选择是否展示该调用示例。

    • 编辑调用说明：支持根据业务场景修改API调用说明。

  4. 根据调用示例说明，进行调用API。

API返回条数

完成调用API后，即可查询数据。当API的调用模式为同步调用时，最大返回查询条数为10000；同步调用和异步调用的查询总条数均不限制。

数据源类型

是否支持分页查询

单物理表服务单元

MySQL/Amazon RDS for MySQL

支持

AnalyticDB for MySQL2.0

支持

ElasticSearch

支持

Microsoft SQL Server/Amazon RDS for SQL Server

不支持

PostgreSQL/Amazon RDS for PostgreSQL

支持

AnalyticDB for MySQL3.0

支持

AnalyticDB for PostgreSQL

支持

Hologres

支持

Hbase（0.9.4/1.1.x/1.2.1/2.x）

支持

Oracle/Amazon RDS for Oracle

支持

MongoDB

支持

DM（达梦）

不支持

Amazon Redshift

不支持

OceanBase

不支持

多物理表服务单元

MySQL/Amazon RDS for MySQL

支持

AnalyticDB for MySQL2.0

支持

ElasticSearch

支持

Microsoft SQL Server/Amazon RDS for SQL Server

不支持

PostgreSQL/Amazon RDS for PostgreSQL

支持

AnalyticDB for MySQL3.0

支持

AnalyticDB for PostgreSQL

支持

Hologres

支持

Hbase（0.9.4/1.1.x/1.2.1/2.x）

支持

Oracle/Amazon RDS for Oracle

支持

MongoDB

支持

DM（达梦）

支持

Amazon Redshift

不支持

OceanBase

不支持

直连数据源API

Impala

支持

Oracle/Amazon RDS for Oracle

支持

MySQL/Amazon RDS for MySQL

支持

PostgreSQL/Amazon RDS for PostgreSQL

支持

Microsoft SQL Server/Amazon RDS for SQL Server

支持

Hologres

支持

Lindorm

支持

ClickHouse

支持

StarRocks

支持

TDengine

不支持

SAP HANA

不支持

SelectDB

支持

Hbase（0.9.4/1.1.x/1.2.1/2.x）

不支持

ElasticSearch

支持

DM（达梦）

支持

Amazon Redshift

支持

GaussDB（DWS）

支持

OceanBase

支持

TDH Inceptor

支持

MaxCompute

支持

Databricks

支持

逻辑表API

不涉及

支持

上一篇：新建及管理我的应用下一篇：附录：API调用示例