配置

一旦安装了pygeoapi，就可以设置配置了。pygeoapi的运行时配置在 YAML 然后通过 PYGEOAPI_CONFIG 环境变量。您可以随意命名文件；典型的文件名以 .yml .

备注

在pygeoapi中总是可以找到一个示例配置 GitHub 储存库。

pygeoapi配置包含以下核心部分：

server ：服务器范围的设置
logging ：日志记录配置
metadata ：服务器范围的元数据（联系人、许可证等）
resources ：服务器提供的数据集集合、进程和stac集合

可以找到完整的配置方案，其中包含所有可用属性的说明 here 。

备注

Standard YAML mechanisms 可用于重复使用和紧凑性（锚、参考等）。

下面通过带注释的示例描述配置指令和引用。

参考文献

`server`

这个 server 部分提供有关绑定和高级调优的指令。

有关API设计规则的更多信息( api_rules 属性)请参见 API设计规则。

server:
  bind:
      host: 0.0.0.0  # listening address for incoming connections
      port: 5000  # listening port for incoming connections
  url: http://localhost:5000/  # url of server
  mimetype: application/json; charset=UTF-8  # default MIME type
  encoding: utf-8  # default server encoding
  language: en-US  # default server language
  locale_dir: /path/to/translations
  gzip: false # default server config to gzip/compress responses to requests with gzip in the Accept-Encoding header
  cors: true  # boolean on whether server should support CORS
  pretty_print: true  # whether JSON responses should be pretty-printed
  limit: 10  # server limit on number of items to return

  templates: # optional configuration to specify a different set of templates for HTML pages. Recommend using absolute paths. Omit this to use the default provided templates
    path: /path/to/jinja2/templates/folder # path to templates folder containing the Jinja2 template HTML files
    static: /path/to/static/folder # path to static folder containing css, js, images and other static files referenced by the template

  map:  # leaflet map setup for HTML pages
      url: https://maps.wikimedia.org/osm-intl/{z}/{x}/{y}.png
      attribution: '<a href="https://wikimediafoundation.org/wiki/Maps_Terms_of_Use">Wikimedia maps</a> | Map data &copy; <a href="https://openstreetmap.org/copyright">OpenStreetMap contributors</a>'
  ogc_schemas_location: /opt/schemas.opengis.net  # local copy of https://schemas.opengis.net

  manager:  # optional OGC API - Processes asynchronous job management
      name: TinyDB  # plugin name (see pygeoapi.plugin for supported process_manager's)
      connection: /tmp/pygeoapi-process-manager.db  # connection info to store jobs (e.g. filepath)
      output_dir: /tmp/  # temporary file area for storing job results (files)

  api_rules:  # optional API design rules to which pygeoapi should adhere
      api_version: 1.2.3  # omit to use pygeoapi's software version
      strict_slashes: true  # trailing slashes will not be allowed and result in a 404
      url_prefix: 'v{api_major}'  # adds a /v1 prefix to all URL paths
      version_header: X-API-Version  # add a response header of this name with the API version

`logging`

这个 logging 节提供用于记录对调试有用的消息的指令。

logging:
    level: ERROR  # the logging level (see https://docs.python.org/3/library/logging.html#logging-levels)
    logfile: /path/to/pygeoapi.log  # the full file path to the logfile

备注

如果 level 定义和 logfile 未定义，则日志消息将输出到服务器的 stdout .

`metadata`

这个 metadata 部分提供总体服务元数据和描述的设置。

metadata:
    identification:
        title: pygeoapi default instance  # the title of the service
        description: pygeoapi provides an API to geospatial data  # some descriptive text about the service
        keywords:  # list of keywords about the service
            - geospatial
            - data
            - api
        keywords_type: theme  # keyword type as per the ISO 19115 MD_KeywordTypeCode codelist. Accepted values are discipline, temporal, place, theme, stratum
        terms_of_service: https://creativecommons.org/licenses/by/4.0/  # terms of service
        url: http://example.org  # informative URL about the service
    license:  # licensing details
        name: CC-BY 4.0 license
        url: https://creativecommons.org/licenses/by/4.0/
    provider:  # service provider details
        name: Organization Name
        url: https://pygeoapi.io
    contact:  # service contact details
        name: Lastname, Firstname
        position: Position Title
        address: Mailing Address
        city: City
        stateorprovince: Administrative Area
        postalcode: Zip or Postal Code
        country: Country
        phone: +xx-xxx-xxx-xxxx
        fax: +xx-xxx-xxx-xxxx
        email: you@example.org
        url: Contact URL
        hours: Mo-Fr 08:00-17:00
        instructions: During hours of service. Off on weekends.
        role: pointOfContact

`resources`

这个 resources 部分列出了服务器要发布的1个或多个数据集集合。资源名称的关键字是通告的集合标识符。

这个 resource.type 属性是必需的。允许的类型包括：

collection
process
stac-collection

这个 providers block是用于操作数据的1..n提供程序的列表。每个提供程序都需要 type 财产。允许的类型包括：

feature
coverage
tile

集合的默认提供程序可以用限定 default: true 在提供程序配置中。如果 default 不包括第一提供程序被假定为默认值。

resources:
    obs:
        type: collection  # REQUIRED (collection, process, or stac-collection)
        visibility: default  # OPTIONAL
        title: Observations  # title of dataset
        description: My cool observations  # abstract of dataset
        keywords:  # list of related keywords
            - observations
            - monitoring
        linked-data: # linked data configuration (see Linked Data section)
            item_template: tests/data/base.jsonld
            context:
                - datetime: https://schema.org/DateTime
                - vocab: https://example.com/vocab#
                  stn_id: "vocab:stn_id"
                  value: "vocab:value"
        links:  # list of 1..n related links
            - type: text/csv  # MIME type
              rel: canonical  # link relations per https://www.iana.org/assignments/link-relations/link-relations.xhtml
              title: data  # title
              href: https://github.com/mapserver/mapserver/blob/branch-7-0/msautotest/wxs/data/obs.csv  # URL
              hreflang: en-US  # language
        extents:  # spatial and temporal extents
            spatial:  # required
                bbox: [-180,-90,180,90]  # list of minx, miny, maxx, maxy
                crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84  # CRS
            temporal:  # optional
                begin: 2000-10-30T18:24:39Z  # start datetime in RFC3339
                end: 2007-10-30T08:57:29Z  # end datetime in RFC3339
        providers:  # list of 1..n required connections information
            # provider name
            # see pygeoapi.plugin for supported providers
            # for custom built plugins, use the import path (e.g. mypackage.provider.MyProvider)
            # see Plugins section for more information
            - type: feature # underlying data geospatial type: (allowed values are: feature, coverage, record, tile, edr)
              default: true  # optional: if not specified, the first provider definition is considered the default
              name: CSV
              data: tests/data/obs.csv  # required: the data filesystem path or URL, depending on plugin setup
              id_field: id  # required for vector data, the field corresponding to the ID
              uri_field: uri # optional field corresponding to the Uniform Resource Identifier (see Linked Data section)
              time_field: datetimestamp  # optional field corresponding to the temporal property of the dataset
              title_field: foo # optional field of which property to display as title/label on HTML pages
              properties:  # optional: only return the following properties, in order
                  - stn_id
                  - value
              # editable transactions: DO NOT ACTIVATE unless you have setup access control beyond pygeoapi
              editable: true  # optional: if backend is writable, default is false
              # coordinate reference systems (CRS) section is optional
              # default CRSs are http://www.opengis.net/def/crs/OGC/1.3/CRS84 (coordinates without height)
              # and http://www.opengis.net/def/crs/OGC/1.3/CRS84h (coordinates with ellipsoidal height)
              crs: # supported coordinate reference systems (CRS) for 'crs' and 'bbox-crs' query parameters
                  - http://www.opengis.net/def/crs/EPSG/0/28992
                  - http://www.opengis.net/def/crs/OGC/1.3/CRS84
                  - http://www.opengis.net/def/crs/EPSG/0/4326
              storage_crs: http://www.opengis.net/def/crs/OGC/1.3/CRS84 # optional CRS in which data is stored, default: as 'crs' field
              storage_crs_coordinate_epoch: : 2017.23 # optional, if storage_crs is a dynamic coordinate reference system
              format:  # optional default format
                  name: GeoJSON  # required: format name
                  mimetype: application/json  # required: format mimetype
              options:  # optional options to pass to provider (i.e. GDAL creation)
                  option_name: option_value

    hello-world:  # name of process
        type: collection  # REQUIRED (collection, process, or stac-collection)
        processor:
            name: HelloWorld  # Python path of process definition

参见

Linked Data 用于可选地配置链接数据集

参见

自定义pygeoapi:插件有关插件的更多信息

添加到集合的链接

可以将任何类型的链接添加到类型为 collection 。只要链接有一个 type ， rel ，以及 href 参数。这个 type 参数定义MIME类型 (Content-Type )链接的资源。这个 rel 参数告诉我们它是哪种类型的链接。您可以将其设置为 license 要添加数据许可证链接，或 describedBy 例如，如果您希望添加模式定义。

还可以向集合添加(批量)下载链接。这些链接应该有他们的 rel 参数设置为 enclosure 并且必须有一个 length 定义文件内容长度(字节大小)的参数。如果你知道内容长度，并且它永远不会改变，你可以设置它，PYOGIAPI将按原样返回附件链接(S)。

然而，可下载资源可能会发生变化(例如，它的大小可能会随着时间的推移而增长)。在这种情况下，您可以省略 length 而比利亚皮会弄清楚真正的 Content-Length 标头，通过发出 HEAD 对给定URL的请求 (href 参数)。此外，如果它注意到定义的 type (MIME类型)的链接与实际的 Content-Type 在响应标头中，它将自动更新 type 相应地。请注意 type 是强制链接参数，因此您必须始终设置它。

例如，您可以按如下方式定义下载链接：

links
  - type: application/octet-stream  # must have some MIME type
    rel: enclosure
    title: download link
    href: https://myserver.com/data/file.zip  # URL

而比利亚皮将会把它变成：

{
  "links": {
    "type": "application/zip",
    "rel": "enclosure",
    "title": "download link",
    "href": "https://myserver.com/data/file.zip",
    "length": 46435
  }
}

请注意如何更新MIME类型以匹配实际的 Content-Type 而且那个 length 是根据 Content-Length 标题。

备注

如果 length 参数被省略，并且pygeapi无法验证 Content-Length 在1秒内和/或1个URL重定向内，附件链接将 not 被包括在回应中。这意味着，如果要确保始终包含该链接，则必须设置 length 。

发布隐藏资源

Pygeapi允许发布资源，而无需通过其集合和OpenAPI端点显式地通告它们。如果客户端先验地知道资源的名称，则资源是可用的。

若要提供隐藏资源，资源必须提供 visibility: hidden 财产。例如，考虑以下资源：

resources:
     foo:
         title: my hidden resource
         visibility: hidden

例如：

curl https://example.org/collections  # resource foo is not advertised
curl https://example.org/openapi  # resource foo is not advertised
curl https://example.org/collections/foo  # user can access resource normally

API设计规则

某些pygeapi设置可能希望遵守适用于组织的特定API设计规则。这个 api_rules 对象中的 server 配置的一节可用于此目的。

请注意，整个 api_rules 对象是可选的。如果省略该对象，则不会应用任何规则。

可以设置以下属性：

`api_version`

如果指定，则此属性是定义API语义版本号的字符串。请注意，此数字应反映 API data model (请求和响应对象结构、API端点等)并且不一定对应于 software 比利亚皮的版本。例如，软件可以完全重写(这会更改软件版本号)，但API数据模型可能仍然与以前相同。

遗憾的是，pygeapi目前没有提供跟踪API版本的方法。这意味着您需要在此处设置(和维护)您自己的版本，或者将其保留为空或不设置。在后一种情况下，将使用软件版本的pygeapi。

`strict_slashes`

一些API规则规定，如果URL末尾的斜杠指向特定的资源项，则不允许使用它们。在这种情况下，您可能希望将此属性设置为 true. Doing so will result in a 404 Not Found if a user adds a / to the end of a URL. If omitted or `` False``(默认)，则无论用户是省略还是添加 / 添加到URL的末尾。

`url_prefix`

设置此属性以在URL路径中包括前缀(例如 https://base.com/<my_prefix>/endpoint )。请注意，您不需要在此处包括斜杠(无论是在开头还是结尾)：它们将自动添加。

如果您希望包括API版本号(取决于 api_version 属性)在前缀中，可以使用以下变量：

{api_version} ：全语义版本号
{api_major} ：主版本号
{api_minor} ：次要版本号
{api_build} ：内部版本号

例如，如果API版本为 1.2.3 ，然后是URL前缀模板 v{api_major} 将导致 v1 作为实际的前缀。

`version_header`

设置此属性可向每个包含语义API版本的pygeapi响应添加标头(请参见 api_version )。如果省略，则不会添加任何标头。此标头的常见名称为 API-Version 或 X-API-Version 。注意，pygeapi已经添加了一个 X-Powered-By 默认情况下包含软件版本号的标头。

正在验证配置

为确保您的配置有效，pyGeoapi提供了一个验证实用程序，可按如下方式运行：

pygeoapi config validate -c /path/to/my-pygeoapi-config.yml

使用环境变量

pygeoapi配置支持使用系统环境变量，这有助于部署到 12 factor 例如环境。

下面是一个如何在pygeoapi中集成系统环境变量的示例。

server:
    bind:
        host: ${MY_HOST}
        port: ${MY_PORT}

层次化集合

中定义的集合 resources 节由资源键标识。资源名称的关键字是通告的集合标识符。例如，给定以下内容：

resources:
  lakes:
    ...

由此产生的集合将在http://localhost:5000/collections/lakes上提供

默认情况下，所有集合都发布到http://localhost:5000/collections.要启用分层收集，请在资源键中提供分层结构。考虑到以下情况：

resources:
  naturalearth/lakes:
    ...

最终得到的集合将在http://localhost:5000/collections/naturalearth/lakes上提供

备注

考虑到分层集合扩展规范在OGC中的演变方式，该功能在未来可能会发生变化。

备注

集合分组不可用。这意味着，虽然http://localhost:5000/collections/naturalearth/lakes等URL的功能与预期一致，但http://localhost:5000/collections/naturalearth等URL不会提供聚合集合列表或查询。该功能也将基于OGC的分层集合扩展规范的演变来确定。

要素和记录提供程序中的选择性属性

中定义的提供程序 providers 部分的特征/记录集合定义可以支持选择性特性，以仅返回模式属性的子集。这允许专门化可查询对象的行为和在有效负载中返回的GeoJSON属性。

例如，给出上面的 lakes 集合对其提供程序返回的架构属性的限制可以使用以下内容定义：

resources:
  lakes:
    ...
    providers:
      - type: feature
        name: ...
        data:
          ...
        properties:
          - name

例如：

curl https://example.org/collections/lakes/queryables  # only the name definition is returned
curl https://example.org/collections/lakes/items  # only the name attribute is returned in properties
curl https://example.org/collections/lakes/items/{item_id}  # only the name attribute is returned in properties

链接数据

pygeoapi支持关于已部署实例的结构化元数据，并且还能够将数据表示为结构化数据。 JSON-LD 每个HTML页面都有等价物，并作为数据块嵌入到相应的页面中，以进行搜索引擎优化（SEO）。工具，如 Google Structured Data Testing Tool 可用于检查结构化表示。

实例的元数据由 metadata 配置的部分。此元数据是自动包含的，足以包含在数据集的主要索引中，包括 Google Dataset Search .

对于集合，在项目级别，默认的JSON-LD表示添加：

一个 @id 项的URL，即该项的URL。如果指定了uri_field，则使用它，否则URL指向其在pyGeoapi中的HTML表示。
分开GeoSPARQL/WKT和 schema.org/geo 几何体的版本。 schema.org/geo 仅支持点、线和多边形几何图形。多部分线合并为一条线。通过一元并集或凸壳变换，将多部分几何的睡觉进行约简，转化为多边形。
@context 用于GeoSPARQL和模式几何图形。
将解包后的属性挡路放入项目主体中。

对于集合，在项目级别，默认的JSON-LD表示添加：

的schema.org项列表 @id 和 @type 集合中每个功能的。

物料层的集合的可选配置选项包括：

如果 uri_field 则将更新JSON-LD，以便 @id 具有的值为 uri_field 对于集合中的每一项

备注

虽然这足以提供有效的RDF（如GeoJSON LD），但它不允许性质你的项目是明确的解释。

pygeoapi当前允许扩展 @context 允许属性别名为词汇表中的术语。这是通过添加 context 配置的节 dataset .

默认的pygeoapi配置包括 obs 示例数据集：

linked-data:
  context:
    - datetime: https://schema.org/DateTime
    - vocab: https://example.com/vocab#
      stn_id: "vocab:stn_id"
      value: "vocab:value"

这是一个不存在的词汇表，仅用于说明配置中的预期数据结构。特别是 stn_id 和 value 属性无法解析。我们可以将这个例子扩展到一个用架构.org:

linked-data:
  context:
    - schema: https://schema.org/
      stn_id: schema:identifier
      datetime:
          "@id": schema:observationDate
          "@type": schema:DateTime
      value:
          "@id": schema:value
          "@type": schema:Number

现在，这一点已经被详细阐述，结构化数据表示的好处变得更加清楚。曾经被称为无法解释的财产 datetime 在源CSV中，现在可以 expanded 到 https://schema.org/observationDate ，从而消除歧义并增强互操作性。其类型也表示为 https://schema.org/DateTime .

此示例演示如何使用包含的示例数据将此功能与CSV数据提供程序一起使用。JSON-LD结构化数据的实现可用于任何数据提供程序，但目前仅限于定义 @context . 可以表示项之间的关系，但依赖于由数据集提供程序而不是pygeoapi来表示的关系。

包含项之间关系的数据提供程序的一个示例是SensorThings API提供程序。默认情况下，SensorThings API在其数据模型中具有实体之间的关系。设置 intralink 的SensorThings提供程序的字段 true 将pygeapi设置为将已配置实体之间的关系表示为内部pygeapi链接或URI。这种关系可以在JSON-LD结构化数据中使用适当的 @context 使用SOSA/SSN本体。例如：

Things:
  linked-data:
    context:
      - sosa: "http://www.w3.org/ns/sosa/"
        ssn: "http://www.w3.org/ns/ssn/"
        Datastreams: sosa:ObservationCollection

Datastreams:
  linked-data:
    context:
      - sosa: "http://www.w3.org/ns/sosa/"
        ssn: "http://www.w3.org/ns/ssn/"
        Observations: sosa:hasMember
        Thing: sosa:hasFeatureOfInterest

Observations:
  linked-data:
    context:
      - sosa: "http://www.w3.org/ns/sosa/"
        ssn: "http://www.w3.org/ns/ssn/"
        Datastream: sosa:isMemberOf

有时，集合中的单个特性所需的JSON-LD比使用上下文为属性设置别名所能实现的更复杂。在这种情况下，可以指定JJIA2模板。什么时候 item_template 是为要素集合定义的，则由pygeapi准备的json-ld将用于呈现路径指定的JJIA2模板。指定的路径可以是绝对路径，也可以是相对于pygeapi的模板文件夹的路径。为了获得更大的部署灵活性，可以使用环境变量的字符串内插来指定路径。

linked-data:
  item_template: tests/data/base.jsonld
  context:
    - datetime: https://schema.org/DateTime

备注

模板 tests/data/base.jsonld 呈现未修改的JSON-LD。有关JJIA2模板容量的更多信息，请参见 HTML模板。

总结

此时，您已准备好管理服务器的配置。

配置

参考文献

server

logging

metadata

resources