Proto-Definitionen¶

Die .proto-Dateien sind die maßgebliche Spezifikation der gRPC-Schnittstelle: Die REST-Routen werden daraus abgeleitet, das .NET SDK baut auf dem daraus generierten Vertrag auf. Für Sprachen ohne SDK erzeugst du die Client-Stubs aus diesen Dateien selbst.

Herunterladen¶

Stand	Download
Entwicklungsstand (`master`, `5c1c11a8`)	zedal-protos-latest.zip
Release `1.3.0`	zedal-protos-1.3.0.zip

Ein Release trägt die Version des NuGet-Pakets Zedal.GrpcApis, das dieselben .proto-Dateien enthält. Der Entwicklungsstand kann Änderungen enthalten, die noch in keinem Release stehen.

Aufbau¶

Die Ordner im Archiv entsprechen den Proto-Paketen. Die import-Anweisungen sind relativ zum obersten Ordner des Archivs, etwa import "core/v1/common_types.proto";; gib diesen Ordner deshalb als Include-Pfad an.

Die Dienste stehen in den Dateien *_api.proto, unter anderem:

Datei	Dienste
`core/v1/*_api.proto`	`AuthApi`, `DocumentApi`, `DocumentTemplateApi`, `FileApi`, `CommonApi`, `MasterdataApi`, `QueryApi` und weitere
`bxa/diwass/v1/api/*_api.proto`	`CompanyDocumentApi`, `AuthorityDocumentApi`, `DocumentBlockApi`
`bxa/bmu/v1/api/bmu_document_api.proto`	`BmuDocumentApi`
`diwass/v1/api/*_api.proto`	`OperatorApi`, `AuthorityApi`, `RetrievalApi`, `AttachmentApi`, `SoapProxyApi`
`provider_discovery/v1/api/discovery_api.proto`	`DiscoveryApi`
`signer/sign/v1/api/*-api.proto`, `signer/cis/v1/api/certificate-info-api.proto`, `signer/v2/api/verify-api.proto`	`SignerApi`, `SignerHandoffApi`, `SignerDeviceApi`, `SignerEntitlementApi`, `SignerSettingsApi`, `CertificateInfoApi`, `VerifyApi`

Die Nachrichten stehen in den übrigen Dateien, die Dokumentmodelle unter documents/v1/. Die Annotationen, auf die die Protos verweisen (google/api, google/rpc, protoc-gen-openapiv2, openapiv3), liegen mit im Archiv. Die Standardtypen unter google/protobuf/ bringt der Protobuf-Compiler mit.

Stubs erzeugen¶

Beispiel für Python mit grpcio-tools, im Ordner mit dem entpackten Archiv:

pip install grpcio-tools
mkdir -p generated
python -m grpc_tools.protoc -I zedal-protos-<version> \
  --python_out=generated --grpc_python_out=generated \
  $(find zedal-protos-<version> -name '*.proto')

Der Zielordner muss vorher existieren. Danach liegen die Module unter generated/, etwa generated/core/v1/auth_api_pb2_grpc.py mit AuthApiStub. Für andere Sprachen gilt dasselbe mit protoc und dem Plugin der Sprache.

Endpunkte, Authentifizierung und Timeouts stehen unter gRPC.