OGC API - Records¶

Público-alvo

Estudantes familiarizados com serviços web e APIs, que desejam ter uma visão geral da norma OGC API - Records

Objetivos de Aprendizagem

Ao concluir o módulo, os estudantes serão capazes de:

Explicar o que é a norma OGC API - Records
Descrever o que pode ser feito com implementações da OGC API - Records
Compreender os principais recursos oferecidos por implementações da OGC API - Records
Compreender como obter uma descrição das capacidades de uma implementação da OGC API - Records
Compreender como fazer pedidos a uma implementação do OGC API - Records
Conseguir encontrar um endpoint do OGC API - Records e utilizá-lo através de um cliente

Introdução¶

A OGC API - Records é uma norma multi-parte que oferece a capacidade de criar, modificar e consultar metadados na Web. A norma permite a descoberta de recursos geoespaciais ao padronizar a forma como as coleções de informação descritiva sobre os recursos (metadados) são expostas. A norma também permite a descoberta e partilha de recursos relacionados que possam ser referenciados a partir de recursos geoespaciais ou dos respetivos metadados, padronizando a forma como todos os tipos de registos são expostos e geridos. A Parte 1 cobre o acesso apenas-leitura a registos e capacidades simples de consulta. Capacidades adicionais que abordam necessidades específicas serão especificadas em partes adicionais. Capacidades para consultas mais ricas ou para criar, atualizar ou eliminar registos serão especificadas em partes adicionais.

Note

A OGC API - Records aproveita a OGC API - Features como base, com endpoints de URL semelhantes e fluxo de trabalho de pedido/resposta, para o Catálogo Pesquisável e Local.

Note

Este módulo tutorial não tem a intenção de substituir a própria norma OGC API - Records - Parte 1: Core. O tutorial concentra-se intencionalmente num subconjunto de capacidades com o propósito de ser uma iniciação à utilização da norma. Consulte a norma da OGC API - Records - Parte 1: Core para mais detalhes.

Antecedentes¶

Histórico

O trabalho do standard OGC API - Records foi iniciado em 2018 e foi originalmente designado por OGC CAT4.0. Desde então, seguiu o desenvolvimento do OGC API - Features como base.

Versões

OGC API - Records - Parte 1: Core versão 1.0.0 é a versão mais recente

Suite de testes

Atualmente não existem suites de testes implementadas; uma vez implementadas elas estarão disponíveis no OGC Validator.

Implementações

As implementações podem ser encontradas na página de implementações.

Utilização¶

O OGC API - Records suporta 3 padrões principais de implementação:

Catálogo navegável: navegação e pesquisa de um conjunto de registos de metadados através de ligações
Catálogo pesquisável: capacidade da API para pesquisar e filtrar uma coleção de registos de metadados com base em critérios de pesquisa (bbox, datetime, q, etc.)
Catálogo de recursos locais: funcionalidade de catálogo pesquisável aplicada ao nível da coleção de uma API

A OGC API - Records suporta também um modelo de pesquisa central. Ou seja, um conjunto de propriedades comuns de pesquisa que podem ser utilizadas contra qualquer servidor OGC API - Records, independentemente do formato/standard de metadados e/ou do design do repositório de metadados subjacente.

Note

Para fins deste aprofundamento, vamos focar-nos na norma de implementação de catálogo pesquisável.

Relação com outras normas¶

OGC Catalogue Service for the Web (CSW): A norma CSW é mais apropriada quando se trabalha com aplicações cliente que suportam apenas serviços web clássicos da OGC. Note também que o CSW adota um modelo central de metadados baseado no Dublin Core por predefinição. Em contraste, a OGC API - Records inclui recomendações para suportar HTML e GeoJSON como codificações, quando aplicável. As implementações da OGC API - Records podem também opcionalmente suportar formatos de metadados XML, como ISO 19115/19139.

Visão geral dos recursos¶

A OGC API - Records - Parte 1: Core define os recursos listados na tabela seguinte.

Recurso	Método	Caminho	Propósito
Página de aterragem	GET	/	Este é o recurso de nível superior, que serve como ponto de entrada.
Declaração de conformidade	GET	/conformance	Este recurso apresenta informação sobre a funcionalidade que é implementada pelo servidor.
Definição da API	GET	/api	Este recurso fornece metadados sobre a API propriamente dita. Note que a utilização de /api no servidor é opcional e a definição da API pode estar alojada num servidor completamente separado.
Coleções de registos	GET	/collections	Este recurso lista as coleções de registos oferecidas através da API.
Coleção de registos	GET	/collections/{collectionId}	Este recurso descreve a coleção de registos identificada no caminho.
Acesso a registos	GET	/collections/{collectionId}/items	Este recurso apresenta os registos contidos na coleção.
Recurso central do registo	GET	/collections/{collectionId}/items/{recordId}	Este recurso apresenta o registo identificado no caminho.

Como mencionado anteriormente, a OGC API - Records utiliza intensivamente o\a OGC API - Features como bloco de construção base. Embora a OGC API - Records permita qualquer modelo de metadados, uma diferença e valor acrescentado chave é a capacidade de descrever um modelo central de registo e elementos consultáveis. Isto permite interoperabilidade e integração entre catálogos para descrever recursos geoespaciais de forma consistente.

Por exemplo, um repositório de metadados pode ser modelado seguindo a norma ISO 19115 e ser exposto através da OGC API - Records através de «mapeamento» dos elementos ISO para o modelo central de registo e elementos consultáveis.

O registo central é a unidade atómica de informação num catálogo. Uma descrição completa das propriedades centrais de um registo pode encontrar-se em https://docs.ogc.org/is/20-004r1/20-004r1.html#core-properties. O registo central é uma representação compatível com GeoJSON com elementos fixos no objeto/bloco properties.

Exemplo¶

O servidor de demonstração publica metadados de dados geoespaciais através de uma interface que está em conformidade com a OGC API - Records.

Um exemplo de pedido que pode ser utilizado para recuperar dados da coleção de registos de metadados amostrais do Dutch Nationaal georegister é https://demo.pygeoapi.io/master/collections/dutch-metadata?f=html

Note que a resposta ao pedido é HTML neste caso.

Alternativamente, os mesmos dados podem ser recuperados no formato GeoJSON, através do pedido https://demo.pygeoapi.io/master/collections/dutch-metadata?f=json

Uma aplicação cliente pode, em seguida, recuperar o documento GeoJSON e exibi-lo ou processá-lo.

Recursos¶

Página de Aterragem¶

Dado que a OGC API - Records utiliza o OGC API - Common e a OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação detalhada.

Declarações de conformidade¶

Dado que o OGC API - Records utiliza a OGC API - Common e a OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação detalhada.

Definição da API¶

Dado que a OGC API - Records utiliza o OGC API - Common como bloco de construção, consulte a OGC API - Features para uma explicação detalhada de uma implementação de exemplo.

Coleções de registos¶

Dado que a OGC API - Records utiliza a OGC API - Common e a OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação inicial detalhada.

As descrições de coleções da OGC API - Records fornecem as seguintes propriedades adicionais:

Um título obrigatório para a coleção
Um tipo obrigatório para a coleção
Um indicador obrigatório sobre o tipo dos itens na coleção (record)

Abaixo segue um excerto da resposta ao pedido https://demo.pygeoapi.io/master/collections?f=json, ilustrando um registo de coleção:

{
    "id": "dutch-metadata",
    "type": "Catalog",
    "itemType": "record",
    "title": "Sample metadata records from Dutch Nationaal georegister",
    "description": "Sample metadata records from Dutch Nationaal georegister",
    "keywords":[
        "netherlands",
        "open data",
        "georegister"
    ],
    "links":[
        {
            "type": "application/json",
            "rel": "self",
            "title": "This document as JSON",
            "href": "https://demo.pygeoapi.io/master/collections/dutch-metadata?f=json"
        },
        {
            "type": "application/geo+json",
            "rel": "items",
            "title": "items as GeoJSON",
            "href": "https://demo.pygeoapi.io/master/collections/dutch-metadata/items?f=json"
        }
    ]
}

Coleção de registos¶

Dado que o OGC API - Records utiliza o OGC API - Common e o OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação inicial detalhada, bem como a descrição das Coleções de registos.

Acesso a registos¶

Dado que a OGC API - Records utiliza o OGC API - Common e a OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação detalhada.

Abaixo segue um excerto da resposta ao pedido https://demo.pygeoapi.io/master/collections/dutch-metadata/items?f=json

{
  "type": "FeatureCollection",
  "numberMatched": 308,
  "numberReturned": 10,
  "features": [
    {
      "id": "35149dfb-31d3-431c-a8bc-12a4034dac48",
      "type": "Feature",
      "geometry": {
        "type": "Polygon",
        "coordinates": [
          [
            [
              4.690751953125,
              52.358740234375
            ],
            [
              4.690751953125,
              52.6333984375
            ],
            [
              5.020341796875,
              52.6333984375
            ],
            [
              5.020341796875,
              52.358740234375
            ],
            [
              4.690751953125,
              52.358740234375
            ]
          ]
        ]
      },
      "properties": {
        "created": "2021-12-08",
        "updated": "2022-06-10T01:27:47Z",
        "type": "dataset",
        "title": "Kaartboeck 1635",
        "description": "Data uit kaartboeken van de periode 1635 tot 1775. De kaartboeken werden door het waterschap gebruikt om er op toe te zien dat de eigenaren geen water in beslag namen door demping.\nDe percelen op de kaart zijn naar de huidige maatstaven vrij nauwkeurig gemeten en voorzien van een administratie met de eigenaren. bijzondere locaties van molens werven en beroepen worden in de boeken vermeld. Alle 97 kaarten aan een geven een zeer gedetailleerd beeld van de Voorzaan, Nieuwe Haven en de Achterzaan. De bladen Oost en West van de zaan zijn vrij nauwkeurig. De bladen aan de Voorzaan zijn een schetsmatige weergave van de situatie. De kaart van de Nieuwe Haven si weer nauwkeurig te noemen.",
        "providers": [
          "Team Geo, geo-informatie@zaanstad.nl, Gemeente Zaanstad"
        ],
        "externalIds": [
          {
            "scheme": "default",
            "value": "35149dfb-31d3-431c-a8bc-12a4034dac48"
          }
        ],
        "themes": [
          {
            "concepts": [
              "ARGEOLOGIE",
              "MONUMENTEN",
              "KADASTER",
              "KAARTBOEK",
              "KAARTBOECK",
              "HISTORIE"
            ]
          }
        ],
        "extent": {
          "spatial": {
            "bbox": [
              [
                4.690751953125,
                52.358740234375,
                5.020341796875,
                52.6333984375
              ]
            ],
            "crs": "http://www.opengis.net/def/crs/OGC/1.3/CRS84"
          },
          "temporal": {
            "interval": [
              null,
              null
            ],
            "trs": "http://www.opengis.net/def/uom/ISO-8601/0/Gregorian"
          }
        }
      },
      "links": [
        {
          "href": "https://maps-intern.zaanstad.gem.local/geoserver/wms?SERVICE=WMS",
          "rel": "item",
          "title": "geo:kaartboeck",
          "type": "OGC:WMS"
        },
        {
          "href": "https://maps-intern.zaanstad.gem.local/geoserver/wfs?SERVICE=WFS",
          "rel": "item",
          "title": "geo:kaartboeck",
          "type": "OGC:WFS"
        },
        {
          "href": "https://maps-intern.zaanstad.gem.local/geoserver/wfs?SERVICE=WFS&version=1.0.0&request=GetFeature&typeName=geo:kaartboeck&outputFormat=csv",
          "rel": "item",
          "type": "download"
        },
        {
          "href": "https://maps-intern.zaanstad.gem.local/geoserver/wfs?SERVICE=WFS&version=1.0.0&request=GetFeature&typeName=geo:kaartboeck&outputFormat=shape-zip",
          "rel": "item",
          "type": "download"
        }
      ]
    }

Note que este documento é um documento GeoJSON válido.

O OGC API - Records suporta os mesmos parâmetros de consulta especificados na OGC API - Features. Além disso, o OGC API - Records adiciona um conjunto central de elementos consultáveis fixos. Um exemplo de consulta com base numa pesquisa estilo «motor de pesquisa» utilizando o parâmetro q é https://demo.pygeoapi.io/master/collections/dutch-metadata/items?f=json&q=biomassa

Note

Consulte a norma OGC API - Records - Parte 1: Core para mais informação sobre elementos consultáveis centrais.

Recurso central do registo¶

Dado que o OGC API - Records utiliza a OGC API - Common e o OGC API - Features como blocos de construção, consulte a OGC API - Features para uma explicação detalhada.

GeoJSON¶

A Classe de Requisitos GeoJSON da OGC API - Records especifica uma codificação baseada em GeoJSON para o registo central, com base no RFC7946. Dada a onipresença do GeoJSON, existem inúmeras ferramentas para validar, processar e decodificar/codificar GeoJSON, tornando o GeoJSON da OGC API - Records fácil de incluir em pipelines de processamento de metadados. A OGC API - Records inclui o JSON Schema para a representação GeoJSON e, por conseguinte, pode ser utilizada para validação em tempo de execução ou offline de payloads de metadados. Aplicações baseadas no GeoJSON do OGC API - Records podem estender e restringir o esquema de acordo para fluxos de trabalho específicos do domínio.

Resumo¶

A OGC API - Records fornece funcionalidade para trabalhar com metadados na Web. Este aprofundamento proporcionou uma visão geral da norma e dos vários recursos e endpoints suportados.