Protobuf スキーマをプラットフォームに公開します

目的: Protobuf スキーマを生成してビルドし、プラットフォームに公開します

複雑さ: 初心者向け

所要時間: 20 分

前提条件: 資格情報を取得し、資格情報を確認します

HERE platform では、他のプラットフォームユーザーとパイプラインの間でデータを共有および転送するために使用されるスキーマを定義できます。 HERE platform ポータルは、スキーマアーティファクトを使用して、プラットフォームに保存されているデータを動的にデコードします。プラットフォームは、 Protobuf ファイルを使用してこれらのスキーマを定義します。スキーマは、カタログレイヤー内のパーティションの構造を記述する、関連する Protobuf メッセージのコレクションです (1 つ以上の .proto ファイルに保存されます ) 。一連のアーティファクトで構成される高レベルの構造体です。

このチュートリアルでは、 Protobuf スキーマを生成して構築し、プラットフォームに公開する方法を示します。公開されている Protobuf スキーマに関する情報の取得方法および Protobuf スキーマのダウンロード方法について説明します。

このチュートリアルでは、次のトピックについて説明します。

Protobuf スキーマを生成します
Protobuf スキーマ構造体
既存の Protobuf スキーマで拡張
Protobuf スキーマを検証してパッケージ化します
Protobuf スキーマをプラットフォームに公開します
公開されたスキーマの詳細情報を取得します
スキーマをダウンロードします
Maven 原型を使用します
ベストプラクティス

このチュートリアルでは、 CLI をインストールし、ローカルマシンにプラットフォームとレポジトリ資格情報の両方を設定する必要があります。

プラットフォーム資格情報が正しく設定されていることを確認するには、「資格情報の確認」チュートリアルで予期した結果が返されていることを確認してください。

Protobuf スキーマを生成します

Protobuf スキーマを生成するには、 OLP CLI を使用する方法と Maven 原型を使用する方法の 2 つの方法があります。このチュートリアルでは、 OLP CLI を使用して Protobuf スキーマを生成します。 OLP CLI には、スキーマの新しいMavenプロジェクトを生成するolp schema generateコマンドが用意されています。

注

は olp schema generate 、 Protobuf スキーマ生成に Java JDK を必要とします。 JDK ではなく Java JRE をインストールすると、スキーマの生成に失敗します。

com.here.platform.tutorial グループ ID と generate_protobuf_schema アーティファクト ID を使用して、現在のディレクトリに Protobuf スキーマプロジェクトを生成しましょう。

olp schema generate com.here.platform.tutorial generate_protobuf_schema --type proto

注

グループ ID には、通常、などのグループ ID に対するチーム / 製品の階層が含まれている必要 com.some-company.automated-driving.schemaがあります。このようにして、異なるチームがスキーマを個別に管理できます。

スキーマをアーティファクトサービスに展開すると、そのグループ ID が組織によって予約され、この場合は他のレルムで再利用できなくなります。したがって com.example、、 com.here.schema、、などの汎用グループ ID の値を指定 com.here.exampleすると、スキーマをアーティファクトサービスリポジトリにアップロードできなくなり、カタログで使用したり、他のユーザーと共有したりできなくなります。主な推奨事項は、パッケージ命名のベストプラクティスに従うことです

OLP CLI は次の出力を返します。

Schema has been successfully generated in /home/user/generate_protobuf_schema.

Protobuf スキーマが生成されたら、生成されたプロジェクトの構造を確認できます。

Protobuf スキーマ構造体

olp schema generate このコマンドは、次の構造のプロジェクトを生成します。

generate_protobuf_schema/
├── ds
│   ├── pom.xml
│   └── src
│       ├── assembly
│       │   └── proto.xml
│       └── main
│           └── resources
│               ├── renderers
│               │   └── ReadMe.txt
│               └── ResourcesReadMe.txt
├── java
│   └── pom.xml
├── proto
│   ├── pom.xml
│   └── src
│       ├── assembly
│       │   └── proto.xml
│       └── main
│           ├── proto
│           │   └── com
│           │       └── here
│           │           └── platform
│           │               └── tutorial
│           │                   └── generate_protobuf_schema
│           │                       └── v1
│           │                           └── generate_protobuf_schema.proto
│           └── resources
│               └── description.md
├── scala_2.12
│   └── pom.xml
├── pom.xml
└── schema.yml

上の構造から、生成されたプロジェクトにds、java、proto、scala_2.12モジュール、schema.ymlおよびpom.xmlファイルが含まれていることがわかります。

ds このモジュールには、パーティションの動的デコードに使用される Data スキーマ（ DS; データソース）バンドルが含まれています。スキーマ HERE の GeoJSON レンダラーを配置できます。 HERE platform ポータルでは、レンダラーを使用してベースマップの上にパーティションデータを表示します。 ds/src/main/resources/renderers このフォルダーは、 HERE platform に公開された後にスキーマにバンドルされる GeoJSON レンダラーを配置できる場所です。レンダラーは JavaScript で記述され、 HERE platform ポータルのベースマップの上にパーティションデータを表示するために使用されます。詳細については、 GeoJSON レンダラの実装のドキュメントを参照してください。

proto このモジュールには、スキーマの Protobuf メッセージの定義が含まれています。 proto/src/main/proto/com/here/platform/tutorial/generate_protobuf_schema/v1/generate_protobuf_schema.proto このファイルは、データ形式を記述するメインの Protobuf ファイルです。

syntax = "proto3";

package com.here.platform.tutorial.generate_protobuf_schema.v1;

message MainProtobufMessage {
    int32 lat = 1;
    int32 lon = 2;
}

デフォルトのメイン Protobuf ファイルには、 2 つの必須プロパティ lat および lonint32 タイプを含むデータ形式が記述されています。

メイン Protobuf ファイルの内容は、 Protobuf 構文に準拠している必要があります。

このproto/src/main/resources/description.md ファイルは空のファイルで、スキーマの詳細なドキュメントをマークダウン形式で保存できます。

pom.xml スキーマプロジェクトのルートにあるファイルには name、、 description、などのスキーマの主な詳細情報 versionが含まれています。 pom.xml のデフォルト値を上書きする場合は、olp schema generateコマンドの実行時に、name、descriptionまたは version のパラメータを指定します。

特定のスキーマが依存している他のスキーマの宣言も pom.xml、次の場所に含まれています。

pom.xml


<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<project xmlns="http://maven.apache.org/POM/4.0.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://maven.apache.org/POM/4.0.0 http://maven.apache.org/xsd/maven-4.0.0.xsd">
<modelVersion>4.0.0</modelVersion>
    <groupId>com.here.platform.tutorial</groupId>
    <artifactId>generate_protobuf_schema_v1</artifactId>
    <version>1.0.0</version>
    <packaging>pom</packaging>
    <name>Schema</name>
    <description>Schema project for OLP</description>
    <inceptionYear>2019</inceptionYear>
    <distributionManagement>
        <repository>
            <id>HERE_PLATFORM_ARTIFACT</id>
            <layout>here</layout>
            <!-- This custom url serves to invoke the HERE wagon extension that handles OAUTH
                 and re-writes Maven URIs for the HERE secure repository.-->
            <url>here+artifact-service://artifact-service</url>
        </repository>
    </distributionManagement>
    <parent>
        <groupId>com.here.platform</groupId>
        <artifactId>sdk-standalone-bom_2.12</artifactId>
        <version>2.54.3</version>
    </parent>
    <properties>
        <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
        <maven.compiler.source>1.8</maven.compiler.source>
        <maven.compiler.target>1.8</maven.compiler.target>
        <protobuf.version>3.11.4</protobuf.version>
        <protoc.version>3.11.4</protoc.version>
        <here.plugin.version>2.1.20</here.plugin.version>
        <artifact.wagon.version>2.0.19</artifact.wagon.version>
    </properties>
    <dependencyManagement>
        <dependencies>
            <dependency>
                <groupId>com.google.protobuf</groupId>
                <artifactId>protobuf-java</artifactId>
                <version>${protobuf.version}</version>
                <scope>compile</scope>
            </dependency>
        </dependencies>
    </dependencyManagement>
    <repositories>
        <repository>
            <id>HERE_PLATFORM_ARTIFACT</id>
            <layout>here</layout>
            <url>here+artifact-service://artifact-service</url>
        </repository>
    </repositories>
    <build>
        <pluginManagement>
            <plugins>
                <plugin>
                    <groupId>org.eclipse.m2e</groupId>
                    <artifactId>lifecycle-mapping</artifactId>
                    <version>1.0.0</version>
                    <configuration>
                        <lifecycleMappingMetadata>
                            <pluginExecutions>
                                <pluginExecution>
                                    <pluginExecutionFilter>
                                        <groupId>com.here.platform.schema.maven_plugins</groupId>
                                        <artifactId>proto-unpack-plugin</artifactId>
                                        <versionRange>[0.0.1,)</versionRange>
                                        <goals>
                                            <goal>unpack</goal>
                                        </goals>
                                    </pluginExecutionFilter>
                                    <action>
                                        <execute>
                                            <runOnIncremental>false</runOnIncremental>
                                        </execute>
                                    </action>
                                </pluginExecution>
                                <pluginExecution>
                                    <pluginExecutionFilter>
                                        <groupId>net.alchim31.maven</groupId>
                                        <artifactId>scala-maven-plugin</artifactId>
                                        <versionRange>[0.0.1,)</versionRange>
                                        <goals>
                                            <goal>compile</goal>
                                        </goals>
                                    </pluginExecutionFilter>
                                    <action>
                                        <execute>
                                            <runOnIncremental>false</runOnIncremental>
                                        </execute>
                                    </action>
                                </pluginExecution>
                            </pluginExecutions>
                        </lifecycleMappingMetadata>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>com.here.platform.schema.maven_plugins</groupId>
                    <artifactId>proto-unpack-plugin</artifactId>
                    <version>${here.plugin.version}</version>
                    <executions>
                        <execution>
                            <id>unpack</id>
                            <phase>validate</phase>
                            <goals>
                                <goal>unpack</goal>
                            </goals>
                        </execution>
                    </executions>
                    <configuration>
                        <outputDirectory>${project.build.directory}/proto</outputDirectory>
                    </configuration>
                </plugin>
                <plugin>
                    <groupId>org.apache.maven.plugins</groupId>
                    <artifactId>maven-source-plugin</artifactId>
                    <version>3.0.1</version>
                    <executions>
                        <execution>
                            <id>attach-sources</id>
                            <phase>verify</phase>
                            <goals>
                                <goal>jar-no-fork</goal>
                            </goals>
                        </execution>
                    </executions>
                </plugin>
            </plugins>
        </pluginManagement>
        <plugins>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-antrun-plugin</artifactId>
                <version>1.7</version>
                <inherited>false</inherited>
                <executions>
                    <execution>
                        <id>copy-schema</id>
                        <phase>package</phase>
                        <goals>
                            <goal>run</goal>
                        </goals>
                        <configuration>
                            <target>
                                <echoproperties destfile="${project.build.directory}/build.properties"/>
                                <copy file="${project.basedir}/schema.yml" overwrite="true" todir="${project.build.directory}">
                                    <filterset begintoken="${" endtoken="}" filtersfile="${project.build.directory}/build.properties"/>
                                </copy>
                            </target>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.apache.maven.plugins</groupId>
                <artifactId>maven-enforcer-plugin</artifactId>
                <version>3.0.0-M2</version>
                <executions>
                    <execution>
                        <id>enforce-property</id>
                        <goals>
                            <goal>enforce</goal>
                        </goals>
                        <configuration>
                            <rules>
                                <requireProperty>
                                    <property>project.groupId</property>
                                    <message>Project groupId must be specified.</message>
                                    <regex>^[a-zA-Z_]+[a-zA-Z0-9_-]*(\.[a-zA-Z0-9_]+[a-zA-Z0-9_-]*)+$</regex>
                                    <regexMessage>Project groupId must be specified as reverse domain name.</regexMessage>
                                </requireProperty>
                            </rules>
                            <fail>true</fail>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>build-helper-maven-plugin</artifactId>
                <version>1.6</version>
                <inherited>false</inherited>
                <executions>
                    <execution>
                        <id>attach-artifacts</id>
                        <phase>package</phase>
                        <goals>
                            <goal>attach-artifact</goal>
                        </goals>
                        <configuration>
                            <artifacts>
                                <artifact>
                                    <file>${project.build.directory}/schema.yml</file>
                                    <type>yml</type>
                                    <classifier>here-schema</classifier>
                                </artifact>
                            </artifacts>
                        </configuration>
                    </execution>
                </executions>
            </plugin>
            <plugin>
                <groupId>org.codehaus.mojo</groupId>
                <artifactId>flatten-maven-plugin</artifactId>
                <version>1.1.0</version>
                <configuration>
                    <flattenMode>bom</flattenMode>
                    <outputDirectory>${project.build.directory}</outputDirectory>
                    <flattenedPomFilename>${project.artifactId}-${project.version}.pom</flattenedPomFilename>
                </configuration>
                <executions>
                    <execution>
                        <id>flatten</id>
                        <phase>process-resources</phase>
                        <goals>
                            <goal>flatten</goal>
                        </goals>
                    </execution>
                    <execution>
                        <id>flatten.clean</id>
                        <phase>clean</phase>
                        <goals>
                            <goal>clean</goal>
                        </goals>
                    </execution>
                </executions>
            </plugin>
        </plugins>
        <extensions>
            <extension>
                <groupId>com.here.platform.artifact</groupId>
                <artifactId>artifact-wagon</artifactId>
                <version>${artifact.wagon.version}</version>
            </extension>
        </extensions>
    </build>
    <modules>  
        <module>proto</module>
        <module>java</module>
        <module>scala_2.12</module>
        <module>ds</module>
    </modules>
</project>

schema.yml プロジェクトのルートにあるファイルは、プロジェクトがスキーマプロジェクトであることを示す記述子ファイルです。

name: "${project.name}"
summary: "${project.description}"
layerSchema: true
type: "proto"

name およびsummaryのプロパティは、それぞれスキーマのnameおよびdescriptionを定義します。デフォルト pom.xml では、これらの値はファイルから取得されます。一般的な目安は、schema.ymlファイル内のこれらのプロパティを変更せず、pom.xmlでのみ定義することです。スキーマの命名およびスキーマの説明については、次のベストプラクティスに従うことをお勧めします

layerSchema このスキーマをスタンドアロンスキーマとして使用するかどうかを定義します。これをに設定 false すると、スキーマは別のスキーマの依存関係としてのみ使用され、プラットフォームにも OLP CLI にも表示されなくなります。

注

プロジェクトがビルドされ、ルートフォルダーに schema.yml ファイルがない状態で展開された場合、スキーマはプラットフォームに表示されません。

既存の Protobuf スキーマで拡張

Protobuf スキーマプロジェクトを作成したら、他の Protobuf スキーマで拡張できます。

このチュートリアルでは proto/src/main/proto/com/here/platform/tutorial/generate_protobuf_schema/v1/generate_protobuf_schema.proto 、追加のプロパティを提供し documentation 、このスキーマをファイルに記述することで、メインの Protobuf ファイルを更新します。

まず、 com.here.schema.rib:address-attributes_v2 依存関係としてパブリックスキーマを追加します。 version プロパティを指定する必要はありません。このプロパティは、 Java/Scala Data SDK の BOM ファイルから取得されます。 HERE 利用可能な依存関係のリストを見つけることができます

ファイルに依存関係 generate_protobuf_schema/proto/pom.xml を追加します。

<dependency>
  <groupId>com.here.schema.rib</groupId>
  <artifactId>address-attributes_v2_proto</artifactId>
  <type>zip</type>
</dependency>

ファイルに依存関係 generate_protobuf_schema/java/pom.xml を追加 :

<dependency>
  <groupId>com.here.schema.rib</groupId>
  <artifactId>address-attributes_v2_java</artifactId>
  <type>jar</type>
</dependency>

ファイルに依存関係 generate_protobuf_schema/scala_2.12/pom.xml を追加 :

<dependency>
  <groupId>com.here.schema.rib</groupId>
  <artifactId>address-attributes_v2_scala_2.12</artifactId>
  <type>jar</type>
</dependency>

com.here.schema.rib:address-attributes_v2 スキーマは、アドレッシング情報を含むアドレスアトリビューションモデルを提供します。これらのモデルは、メインのスキーマメッセージの定義に使用される場合があります。特に、スキーマは com.here.schema.rib.v2.PostalCode 、ファイルで定義 com/here/schema/rib/v2/address_attributes.protoされている郵便番号を記述するモデルを提供します。

postal_code type の新しいプロパティを com.here.schema.rib.v2.PostalCode メインの Protobuf ファイルに追加します。更新されたメイン Protobuf ファイルは次のようになります。

syntax = "proto3";

package com.here.platform.tutorial.generate_protobuf_schema.v1;

import "com/here/schema/rib/v2/address_attributes.proto";

message MainProtobufMessage {
  int32 lat = 1;
  int32 lon = 2;
  com.here.schema.rib.v2.PostalCode postal_code = 3;
}

Protobuf コードのスタイル設定のベストプラクティスに従うことをお勧めします。

次のステップでは、スキーマに関するドキュメントを追加します。

olp schema generate 新しいスキーマプロジェクトを生成するとき --documentation に、パラメーターで OLP CLI コマンドを使用して、準備したドキュメントを追加できます。

ドキュメントをスキーマプロジェクトに渡すには、次の 2 つの方法があります。

外部ドキュメントまたは特定の HERE ドキュメントを参照する場合は、 URL をドキュメントに渡します。
独自のスキーマの説明を含める場合は、マークダウンファイルへのパスを指定します。

すでに生成されたスキーマプロジェクトがあり、ドキュメントを更新または追加する場合は、proto/src/main/resources/description.md ファイルを更新するか、schema.yml ファイルのdocUrl フィールドを追加または更新する必要があります。

proto/src/main/resources/description.md 次のドキュメントをファイルに追加します。

This schema was generated for the `Publish Protobuf schema to the Platform` tutorial.


The main protobuf file describes the data format including the following properties:


`lat` - the measurement of distance north or south of the Equator.

`lon` - the measurement east or west of the prime meridian.

`postal_code` - represents the code generated by the government to facilitate mail delivery.

スキーマプロジェクトが更新されたら、プロジェクトを検証してパッケージ化し、変更内容がプロジェクト自体に影響を与えていないことを確認する必要があります。

Protobuf スキーマを検証してパッケージ化します

OLP CLI に olp schema package は、スキーマプロジェクトをビルドおよび検証するためのコマンドが用意されています。

olp schema package このコマンドは、スキーマプロジェクトを更新し、プラットフォームに展開する前にプロジェクトが有効であることを確認する場合に役立ちます。スキーマを変更しない場合は、このコマンドを使用する必要はありません。

スキーマのビルド中に、次の検証プラグインによって、 Protobuf スキーマプロジェクトに有効なメイン Protobuf ファイルが含まれていることが確認されます。

GoogleStyle バリデータは、スキーマメッセージが Google の Protobuf スタイルガイドに従っていることを確認します。
FileExtension バリデータ .proto は、すべての Protobuf ファイルが拡張子を使用していることを確認します。
MajorVersionInPackage バリデータによって、アーティファクトのメジャーバージョンがパッケージに含まれていることが確認されます。たとえば、バージョン 2.3 のパッケージには「 v2 」が含まれている必要があります。" com.here.platform.schema.foo.v2" 。
BackwardsCompatibility バリデータ .proto は、特定のメジャーバージョン内のファイルの変更内容が下位互換性があることを確認します。変更内容を更新するには、メジャーバージョンの更新が必要です。バリデータは、次の変更を探します。
- ファイルが削除されました
- メッセージが削除されました
- フィールドが削除されました
- フィールドタイプが変更されました
- フィールドラベルが変更されました
- フィールド番号が変更されました
- 列挙型 (enum) を削除しました
- 列挙型 (enum) 値が削除されました
- 列挙型 (enum) 値が変更されました
- プロトタイプの構文が変更されました
PackageConsistency バリデータは、 Protobuf ソースファイルのディレクトリツリーが、個々のファイルの Protobuf パッケージ宣言に対応していることを確認します。

olp schema packageコマンドの実行後、proto/target/proto/META-INF/validation-results.jsonファイルに検証結果が表示されます。

次の OLP CLI コマンドを使用して、更新された Protobuf スキーマプロジェクトをビルドしましょう。

olp schema package --input /home/user/generate_protobuf_schema

OLP CLI は次の出力を返します。

Schema has been packaged successfully.

上記のメッセージは、 Protobuf スキーマプロジェクトが有効で、メインの Protobuf メッセージが Maven プラグインによって検証されたことを示しています。次 proto/target/proto/META-INF/validation-results.json のファイルが生成されます。

{
  "passedValidators" : [ "GoogleStyle", "FileExtension", "MajorVersionInPackage", "BackwardsCompatibility" ]
}

スキーマプロジェクトに無効なメインメッセージファイルがある場合、 olp schema package コマンドは次の出力をログファイルへのパスとともに返します。このログファイルでは、プロジェクトで発生した問題についての追加情報を確認できます。

ERROR: Schema packaging failed.
Log file path: /tmp/olpcli2202976880595062312.log

スキーマプロジェクトでバリデータを無効にするには、 proto/pom.xml および ds/pom.xml ファイルでgoogleStyle、fileExtension、backwardsCompatibility、majorVersionInPackage、packageConsistency、、の設定をfalseに設定します。

<plugin>
  <groupId>com.here.platform.schema.maven_plugins</groupId>
  <artifactId>proto-validate-plugin</artifactId>
  <version>${here.plugin.version}</version>
  <executions>
    <execution>
      <id>validate</id>
      <phase>compile</phase>
      <goals>
        <goal>validate</goal>
      </goals>
    </execution>
  </executions>
  <configuration>
    <googleStyle>false</googleStyle>
    <fileExtension>false</fileExtension>
    <backwardsCompatibility>false</backwardsCompatibility>
    <majorVersionInPackage>false</majorVersionInPackage>
    <ignorePackages>
      <ignorePackage>google.protobuf</ignorePackage>
    </ignorePackages>
  </configuration>
</plugin>

注

プラグインを無効にすることはお勧めしません。無効にすると、スキームが正しく動作しなくなる可能性があります。

プロジェクトが検証およびパッケージ化されたら、プラットフォームに公開できます。

スキーマをプラットフォームに公開します

olp schema put OLP CLI コマンドを使用して、 Protobuf スキーマをプラットフォームに展開してみましょう。

olp schema put --input /home/user/generate_protobuf_schema

OLP CLI は次の出力を返します。


WARNING: Please wait while the command is completed. This may take several minutes.

Schema hrn:here:schema::olp-here:com.here.tutorial:generate_protobuf_schema_v1:1.0.0 has been created.

Please use 'olp schema show' command to get more information.

スキーマが展開されると、 OLP CLI またはポータルで詳細を確認できます。

公開されたスキーマの詳細情報を取得します

次 olp schema show のコマンドを使用して、展開されたスキーマについての詳細情報を取得しましょう。


olp schema show hrn:here:schema::olp-here:com.here.tutorial:generate_protobuf_schema_v1:1.0.0

OLP CLI は、次の情報を返します。


Details of the Schema schema:
schema version           1.0.0
artifact id              generate_protobuf_schema_v1
group id                 com.here.platform.tutorial
type                     proto
summary                  Schema project for OLP

Schema validation results:
module         backwards compatibility       file extension      google style        major version in package      package consistency
proto          true                          true                true                true                          false
ds             false                         false               false               false                         true

Artifacts:
hrn:here:artifact::olp-here:com.here.platform.tutorial:generate_protobuf_schema_v1_java:1.0.0
hrn:here:artifact::olp-here:com.here.platform.tutorial:generate_protobuf_schema_v1_proto:1.0.0
hrn:here:artifact::olp-here:com.here.platform.tutorial:generate_protobuf_schema_v1_scala_2.12:1.0.0
hrn:here:artifact::olp-here:com.here.platform.tutorial:generate_protobuf_schema_v1_ds:1.0.0

上記の出力から、展開されたスキーマ、特にスキーマ version、 group id、、についての一般的な情報を取得します。 artifact idスキーマ type、およびスキーマ summary。スキーマの検証結果は、どのプラグインがどのモジュールに使用されたかを示します。出力の最後のセクションには、アーティファクトの詳細が含まれています。

Protobuf スキーマを展開すると、次の 4 つのアーティファクトも展開されます。_proto、 _ds、_java、 _scala_2.12。

_proto アーティファクトには、 Protobuf メッセージソースを含む zip ファイルが含まれています。アーティファクトには、メインの Protobuf ファイルと JSON 形式の検証結果が含まれています。オプションのファイルはです description.md。このファイルにはドキュメントが含まれています

注

documentation.md ファイルは、schema.ymlファイルのdocUrlプロパティで上書きできます。に docUrl はより高いプライオリティが設定されているため、documentation.mdとdocUrlの両方を指定した場合は、docUrlが使用されます。

スキーマの生成時に documentation.md ファイルを上書きするに olp schema generate は、コマンドで --doc-url <URL to the documentation> パラメーターを使用します。

_ds アーティファクトには、 Protobuf メッセージとデータスキーマ (DS) バンドルを含む zip ファイルが含まれています。 _ds アーティファクトをダウンロードするには、「 Download スキーマ」セクションを参照してください。

_java アーティファクトには、 Java 言語の Protobuf バインディングを含む JAR ファイルが含まれています。

_scala_2.12 アーティファクトには、 Scala 2.12 言語の Protobuf バインディングを含む JAR ファイルが含まれています。

スキーマをダウンロードします

_ds Protobuf メッセージを含むパッケージをダウンロードする olp schema get ために、 OLP CLI にはコマンドが用意されています。


olp schema get hrn:here:schema::olp-here:com.here.tutorial:generate_protobuf_schema_v1:1.0.0 --output ~/Desktop/ds_package

OLP CLI は次の出力を返します。

Schema package was successfully downloaded to ~/Desktop/ds_package/generate_protobuf_schema_v1_ds-1.0.0.zip

ダウンロードされた zip ファイルの構造は次のとおりです。

generate_protobuf_schema_v1_ds-1.0.0/
├── com
│   └── here
│       └── platform
│           └── tutorial
│               └── generate_protobuf_schema
│                   └── v1
│                       └── generate_protobuf_schema.proto
├── google
│   └── protobuf
│       ├── any.proto
│       ├── api.proto
│       ├── compiler
│       │   └── plugin.proto
│       ├── descriptor.proto
│       ├── duration.proto
│       ├── empty.proto
│       ├── field_mask.proto
│       ├── source_context.proto
│       ├── struct.proto
│       ├── timestamp.proto
│       ├── type.proto
│       └── wrappers.proto
├── META-INF
│   ├── layer.fds
│   ├── layer.manifest.json
│   └── validation-results.json
├── renderers
│   └── ReadMe.txt
└── ResourcesReadMe.txt

上記のプロジェクト構造から _ds 、パッケージにメイン generate_protobuf_schema.proto メッセージ、 validation-results.json 検証結果、 layer.manifest.json およびトップレベルメッセージを宣言するマニフェストが含まれていることがわかります。また _ds 、このモジュールには com.google.protobuf 、宣言されたプロトコルバッファの既知のタイプを持つパッケージが含まれています。

Maven 原型を使用します

スキーマを生成、検証、およびアップロードするための追加のオプションがあります。 Protobuf スキーマプロジェクトは Maven プロジェクトなので 'Maven のコマンドを使用してスキーマを操作できますこの目的のために、 Java & Scala 用の Data SDK には project_archetype 、を使用して Protobuf スキーマプロジェクトを生成できるが用意されています。

注

以下のコマンドを実行するに Maven は、ローカルマシンにがインストールされている必要があります。

で Protobuf スキーマプロジェクトを生成 project_archetypeするには、 olp schema generate com.here.platform.tutorial generate_protobuf_schemaProtobuf スキーマを生成セクションのコマンドと同じように、次の Maven コマンドを使用します。

Linux

窓

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema \
-DarchetypeArtifactId=project_archetype \
-DarchetypeVersion=2.1.129 \
-DartifactId=generate_protobuf_schema \
-Dversion=1.0.0 \
-DgroupId=com.here.platform.tutorial \
-DmajorVersion=1

mvn archetype:generate -DarchetypeGroupId=com.here.platform.schema ^
-DarchetypeArtifactId=project_archetype ^
-DarchetypeVersion=2.1.129 ^
-DartifactId=generate_protobuf_schema ^
-Dversion=1.0.0 ^
-DgroupId=com.here.platform.tutorial ^
-DmajorVersion=1

生成されたスキーマを検証してビルドするには、olp schema packageコマンドに類似したプロジェクトのルートからmvn installコマンドを使用します。

olp schema put コマンドを使用せ mvn deploy ずにスキーマを展開するには、生成されたプロジェクトのルートからコマンドを実行します。

スキーマを展開した後、このチュートリアルで説明した OLP CLI コマンドを使用して、そのを検査できます。

ベストプラクティス

この章では、スキーマの作成および整理に関するベストプラクティスについて説明します。これらのガイドラインに従うことで、 HERE platform の一般的な使用感を改善し、スキーマをプラットフォームにアップロードするとき、またはローカルにインストールするときのエラーを最小限に抑えることができます。

スキーマの命名

スキーマの名前を 30 文字に制限してください。このようにすると、スキーマ名が 1 行に収まり、 HERE platform ポータルで簡単に読み取ることができます。

スキーマプロジェクトの POM ファイルで、スキーマの名前を指定できます。 generate_protobuf_schema/pom.xml

スキーマの説明

スキーマの説明に、スキーマの目的を含めます。また、スキーマが他のスキーマに依存している場合は、これらの依存関係を説明にも一覧表示してください。

スキーマの説明をわかりやすく整理するには、 250 文字に制限してください。これにより、スキーマリスト内の 3 行のテキストに変換されます（ HERE platform ポータル > データ > スキーマを参照）。

パッケージの命名

スキーマをプラットフォームにアップロードすると、グループ ID とアーティファクト ID を使用してスキーマの HERE リソースネーム（ HERE リソースネーム）が生成されます。

パッケージ名は、 Protobuf 、 Java 、および Scala のパッケージ名で使用されます。

では groupId、会社の逆のドメイン名を使用します。さらに、チーム / 製品の階層をgroupIdに追加する必要があります ( 例 : com.some-company.automated-driving.schema) 。

注

スキーマがアーティファクトサービスに展開されている場合、その groupId はスキーマ所有者の組織によって予約されています。他の組織のユーザーが同じスキーマを共有している場合 groupId、そのユーザーはスキーマを展開できません。そのため com.example、com.here.schemacom.here.exampleなどの一般的なgroupId値を使用すると、スキーマを Artifact Service レポジトリにアップロードできなくなり、カタログで使用したり、他のユーザーと共有したりできなくなります。

アーティファクト ID には、など、プロジェクトにパッケージ化されているスキーマのタイプに固有の名前 building-footprintsを使用します。アーティファクト ID をできるだけ短くしてください。

Java パッケージの命名規則に従うことをお勧めします。

バージョン管理

スキーマのバージョンを指定するには、セマンティックバージョニングシステム（ SemVer 2.0.0 ）を使用します。

ファイルの命名

スキーマのすべての Protobuf ファイル .proto に拡張子が付いていることを確認してください。

.proto ファイルの命名に snake_case は、スタイルを使用します。 building_footprints_partition.proto locations_partition.proto およびは、適切な Protobuf ファイル名の表示例です。

パッケージの構造化

Protobuf ソースファイルのディレクトリツリーが、個 .proto 々のファイルの Protobuf パッケージ名に対応していることを確認してください。たとえば proto/src/main/proto/com/here/example/v1/test_schema.proto 、ファイルには次のパッケージ宣言が含まれている必要があります。com.here.example.v1。

スキーマで他のスキーマの Protobuf ファイルを使用している場合は import 、個 .proto 々のファイルのステートメントに、インポートされたリソースへのパスが次の形式で含まれていることを確認してください。

パッケージ名の宣言 + imported.posto ファイル名。スラッシュで区切ります

コードのスタイル設定

Protobuf コードには、 Google の Proto3 言語ガイドを使用してください。および Google の Protobuf スタイルガイドに従って、コード内のメッセージ、フィールド、および列挙体の名前を確認します。

結論

このチュートリアルでは、 OLP CLI および Maven を使用して Protobuf スキーマをプラットフォームに生成、構築、および公開する方法を練習しました。また、 Protobuf スキーマ構造体と Protobuf スキーマを操作できる OLP CLI コマンドについても学習しました。

詳細情報

OLP CLI を使用してスキーマを操作する方法の詳細については、『 OLP CLI ガイド』を参照してください。 GeoJSON レンダラを実装します

Protobuf スキーマをプラットフォームに公開します

Protobuf スキーマをプラットフォームに公開します

Protobuf スキーマを生成します

注

注

Protobuf スキーマ構造体

注

既存の Protobuf スキーマで拡張

Protobuf スキーマを検証してパッケージ化します

注

スキーマをプラットフォームに公開します

公開されたスキーマの詳細情報を取得します

注

スキーマをダウンロードします

Maven 原型を使用します

注

ベストプラクティス

スキーマの命名

スキーマの説明

パッケージの命名

注

バージョン管理

ファイルの命名

パッケージの構造化

コードのスタイル設定

結論

詳細情報

「」に一致する結果は件です

「」に一致する結果はありません

開発者

Protobuf スキーマ をプラットフォーム に公開します

Protobuf スキーマ を生成します

注

注

Protobuf スキーマ 構造体

注

既存の Protobuf スキーマ で拡張

Protobuf スキーマ を検証してパッケージ化します

注

スキーマ をプラットフォーム に公開します

公開されたスキーマ の詳細情報を取得します

注

スキーマ をダウンロードします

Maven 原型を使用します

注

ベストプラクティス

スキーマ の命名

スキーマ の説明

パッケージの命名

注

バージョン管理

ファイルの命名

パッケージの構造化

コードのスタイル設定

結論

詳細情報

「」に一致する結果は 件です

「」に一致する結果はありません

開発者

Protobuf スキーマをプラットフォームに公開します

Protobuf スキーマを生成します

Protobuf スキーマ構造体

既存の Protobuf スキーマで拡張

Protobuf スキーマを検証してパッケージ化します

スキーマをプラットフォームに公開します

公開されたスキーマの詳細情報を取得します

スキーマをダウンロードします

スキーマの命名

スキーマの説明

「」に一致する結果は件です