适用于 App Engine 的 Cloud Endpoints Frameworks 命令行工具

本页面介绍了如何使用 Endpoints Frameworks 命令行工具通过 Python 后端 API(在服务器上运行的代码)生成客户端库。任何 Java 或 Android 应用都可以使用此库来调用 API。

您可以生成客户端库软件包,以允许应用使用 Endpoints Frameworks 命令行工具访问您的 API。生成客户端库时,Endpoints Frameworks 命令行工具会自动生成一个发现文档,用于描述您的 API 的接口。

您可以在 Endpoints Frameworks 库中找到 Endpoints Frameworks 命令行工具 endpointscfg.py。如需了解如何使用 pip 安装 Endpoints Frameworks 库,请参阅安装 Endpoints Frameworks 库。请注意,以下命令假定您已在名为 lib 的目录中安装了 Endpoints Frameworks 库。此外,相关说明假定您已创建后端 API。如需查看在示例代码上使用 Endpoints Frameworks 命令行工具的示例,请参阅 Python 版 Endpoint Frameworks 教程

通过 API 生成客户端库软件包

您可以使用 Endpoints Frameworks 命令行工具生成以下类型的客户端软件包:

  • Maven:此软件包包含一个 pom.xml 文件,此文件中包含 Endpoints Frameworks 和 Google API 客户端库依赖项。readme.html 文件详细介绍了对于不同类型的客户端应用您需要向 pom.xml 文件添加的内容,并介绍了如何使用 Maven 为 API 构建客户端库。

  • Gradle:此软件包包含一个 build.gradle 文件,此文件中包含 Endpoints Frameworks 和 Google API 客户端库依赖项。readme.html 文件详细介绍了对于不同类型的客户端应用,您需要向 build.gradle 文件添加的内容,并详细介绍了如何使用 Gradle 为 API 构建客户端库。

  • 默认客户端软件包:此软件包包含所有依赖库和生成的 source.jar 文件,即您在客户端调用 API 时使用的 Java 库。此软件包为您的客户端提供所有 Google API 客户端库功能,包括 OAuth。readme.html 文件列出了不同类型的客户端应用所需的 .jar 文件,以及有关使用客户端库的其他详细信息。

如果您要将客户端库与 Android 应用结合使用,建议您使用 Gradle 客户端软件包。

生成客户端库

如需生成客户端库,请执行以下操作:

  1. 将目录更改为包含 API app.yaml 文件和 API 服务类的目录。或者,使用 --application 选项指定应用目录的其他某个位置。

  2. 调用 Endpoints Frameworks 命令行工具,类似于如下所示:

    lib/endpoints/endpointscfg.py get_client_lib java -bs gradle main.EchoApi
    

    其中 main 是包含 API 的类,EchoApi 是您的 API 名称。

  3. 等待该工具生成客户端库;成功后,该工具会显示一条类似于如下所示的消息:

    API client library written to ./echo-v1.zip
    
  4. 将客户端库 JAR 添加到您的 Android 应用。

  5. 每次修改 API 代码时都重复执行上述步骤。

除非您使用 output 选项指定其他某个输出目录,否则客户端库软件包将写入当前目录中。

命令行语法

基本语法如下所示:

/path-to/your-app/lib/endpointscfg.py get_client_lib TARGET_LANG OPTIONS CLASS_NAME

其中:

  • TARGET_LANG 指定要创建的客户端软件包的类型。目前,您需要提供值 java(对于 Android 等 Java 客户端)。
  • OPTIONS(如果提供)是选项表中显示的一项或多项。
  • CLASS_NAME 是 API 的完全限定类名称。

选项

您可以使用以下选项:

选项名称 说明 示例
application 默认情况下,工具在后端 API 的当前目录中生成客户端软件包。
如果要使用其他目录生成客户端软件包,请指定包含 app.yaml 和用于实现 API 的服务类的目录的路径。
--application /my_path/my_api_dir
build-system 用于指定应生成哪种类型的客户端软件包。可指定 gradle(生成 Android Gradle 客户端软件包)、maven(生成 Maven 客户端软件包)或 default(或省略此选项)(生成仅包含依赖项库和源代码 jar 的软件包)。 --build-system=gradle
-bs gradle
hostname 指定发现文档 rootURL
此选项会替换从后端 API 项目 app.yaml ([YOUR_APP_ID].appspot.com) 中的 application 条目和 API 修饰器中定义的 hostname 派生的默认值。
此选项的一个用途是提供主机名 localhost 作为用于本地测试的 rootURL。
--hostname localhost
format 请不要指定此选项,因为支持的唯一值是默认值,即 rest(对于 REST)。 无需设置此项,请使用默认值。
output 设置将输出写入到的目录。
默认值:从其中调用工具的目录。
--output /mydir
-o /mydir

受支持的客户端平台

Endpoints Frameworks 命令行工具生成的客户端软件包支持以下平台:

通过 API 生成 OpenAPI 文档

endpointscfg.py 工具提供了一个用于通过 API 后端生成 OpenAPI 文档的命令。命令语法如下所示:

lib/endpoints/endpointscfg.py get_openapi_spec
    [-h]
    [-a APPLICATION]
    [--hostname HOSTNAME]
    [-o OUTPUT]
    service [service ...]

positional arguments:
  service               Fully qualified service class name.

optional arguments:
  -h, --help            Show this help message and exit.
  -a APPLICATION, --application APPLICATION
                        The path to the Python App Engine application.
  --hostname HOSTNAME   Default application hostname, if none is specified for the API service.
  -o OUTPUT, --output OUTPUT
                        The directory to store output files.
  --x-google-api-name   Add the 'x-google-api-name' field to the generated OpenAPI document.

例如,使用 echo 示例

$ lib/endpoints/endpointscfg.py get_openapi_spec --hostname=echo-example.appspot.com main.EchoApi
OpenAPI spec written to ./echov1openapi.json