From 1cc444ce7ff39e8e5d112006c7600739bef7da0f Mon Sep 17 00:00:00 2001 From: Daniel Kastl Date: Fri, 14 Jun 2024 15:09:34 +0900 Subject: [PATCH] Improve examples and documentation, fixes #46 Signed-off-by: Daniel Kastl --- .gitignore | 1 + config/locales/de.yml | 4 ++-- config/locales/en.yml | 4 ++-- config/locales/ja.yml | 4 ++-- doc/.env.example | 4 ++++ doc/broker_scripts.md | 4 ++++ doc/examples/camera_sensor.md | 8 +++++++- doc/examples/location_sensor.md | 8 +++++++- doc/examples/temperature_sensor.md | 17 ++++++++++++++--- doc/index.md | 11 +++++++---- doc/scripts/delete_all_subscriptions.sh | 9 +++++++++ doc/scripts/register_all_subscriptions.sh | 9 +++++++++ doc/subscription_template.md | 3 ++- 13 files changed, 70 insertions(+), 16 deletions(-) create mode 100644 doc/.env.example diff --git a/.gitignore b/.gitignore index e43b0f9..be47843 100644 --- a/.gitignore +++ b/.gitignore @@ -1 +1,2 @@ .DS_Store +.env diff --git a/config/locales/de.yml b/config/locales/de.yml index 3df194f..df1ace4 100644 --- a/config/locales/de.yml +++ b/config/locales/de.yml @@ -51,11 +51,11 @@ de: Suchmaske für die Subscription verwendet' gtt_fiware_subscription_template_variable_hint: 'Attributwerte können als ${Variable} eingebettet werden.' - field_subscription_template_expression_coords: 'Koordinaten' + field_subscription_template_expression_coords: 'Koordinaten (lat, lon)' field_subscription_template_standard: 'NGSI-Standard' field_subscription_template_attachments_string: 'Anlagen (Array)' field_subscription_template_fiware_servicepath_placeholder: '/environment' - field_subscription_template_expression_coords_placeholder: '40.419,-3.691;40.429,-3.691;40.429,-3.701' + field_subscription_template_expression_coords_placeholder: "lat1, lon1; lat2, lon2; lat3, lon3; lat1, lon1" field_subscription_template_fiware_service_placeholder: 'smartcity' field_subscription_template_attachments_placeholder: '[{"filename": "image.jpg", "url": "https://example.com/image.jpg"}]' diff --git a/config/locales/en.yml b/config/locales/en.yml index b607554..b90a7f1 100644 --- a/config/locales/en.yml +++ b/config/locales/en.yml @@ -53,8 +53,8 @@ en: field_subscription_template_expression_georel_placeholder: "near;maxDistance:1000" field_subscription_template_expression_geometry: "Geometry" field_subscription_template_expression_geometry_placeholder: "Select a geometry" - field_subscription_template_expression_coords: "Coordinates" - field_subscription_template_expression_coords_placeholder: "40.419,-3.691;40.429,-3.691;40.429,-3.701" + field_subscription_template_expression_coords: "Coordinates (lat, lon)" + field_subscription_template_expression_coords_placeholder: "lat1, lon1; lat2, lon2; lat3, lon3; lat1, lon1" field_subscription_template_alteration_types: "Alteration types" field_subscription_template_notify_on_metadata_change: "Notify on metadata change" diff --git a/config/locales/ja.yml b/config/locales/ja.yml index dc3cc44..90e1986 100644 --- a/config/locales/ja.yml +++ b/config/locales/ja.yml @@ -53,8 +53,8 @@ en: field_subscription_template_expression_georel_placeholder: "near;maxDistance:1000" field_subscription_template_expression_geometry: "Geometry" field_subscription_template_expression_geometry_placeholder: "Select a geometry" - field_subscription_template_expression_coords: "Coordinates" - field_subscription_template_expression_coords_placeholder: "40.419,-3.691;40.429,-3.691;40.429,-3.701" + field_subscription_template_expression_coords: "Coordinates (lat, lon)" + field_subscription_template_expression_coords_placeholder: "lat1, lon1; lat2, lon2; lat3, lon3; lat1, lon1" field_subscription_template_alteration_types: "Alteration types" field_subscription_template_notify_on_metadata_change: "Notify on metadata change" diff --git a/doc/.env.example b/doc/.env.example new file mode 100644 index 0000000..f58b77f --- /dev/null +++ b/doc/.env.example @@ -0,0 +1,4 @@ +BROKER_URL=http://your_broker:1026 +BROKER_TOKEN=your_token +FIWARE_SERVICE=your_service +FIWARE_SERVICEPATH=your_servicepath diff --git a/doc/broker_scripts.md b/doc/broker_scripts.md index 3db149c..b2667d8 100644 --- a/doc/broker_scripts.md +++ b/doc/broker_scripts.md @@ -34,6 +34,8 @@ URL specified in the header for each subscription. `http://app.local:1026` if not set. - `BROKER_TOKEN`: The bearer token for authentication. If provided, it will be used in the `Authorization` header for the requests. +- `FIWARE_SERVICE`: The FIWARE service for the subscriptions (optional). +- `FIWARE_SERVICEPATH`: The FIWARE service path for the subscriptions (optional). **Note:** Make sure to set the `BROKER_URL` and `BROKER_TOKEN` (optional) environment variables to your context broker URL and authentication token respectively @@ -71,6 +73,8 @@ subscriptions, and then makes DELETE requests to the `http://app.local:1026` if not set. - `BROKER_TOKEN`: The bearer token for authentication. If provided, it will be used in the `Authorization` header for the requests. +- `FIWARE_SERVICE`: The FIWARE service for the subscriptions (optional). +- `FIWARE_SERVICEPATH`: The FIWARE service path for the subscriptions (optional). **Note:** This script does not require any arguments. Make sure to set the `BROKER_URL` and `BROKER_TOKEN` (optional) environment variables to your context diff --git a/doc/examples/camera_sensor.md b/doc/examples/camera_sensor.md index 8958672..5f5291d 100644 --- a/doc/examples/camera_sensor.md +++ b/doc/examples/camera_sensor.md @@ -46,6 +46,8 @@ Create the subscription template and publish it. curl -iX POST "${BROKER_URL}/v2/entities" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "id": "urn:ngsi-ld:SpeedCameraSensor:001", "type": "SpeedCameraSensor", @@ -78,6 +80,8 @@ curl -iX PATCH \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:SpeedCameraSensor:001/attrs" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "speed": { "value": 90.0, @@ -91,5 +95,7 @@ curl -iX PATCH \ ```bash curl -iX DELETE \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:SpeedCameraSensor:001" \ - -H "Authorization: Bearer ${BROKER_TOKEN}" + -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" ``` diff --git a/doc/examples/location_sensor.md b/doc/examples/location_sensor.md index ca6fb84..e92f753 100644 --- a/doc/examples/location_sensor.md +++ b/doc/examples/location_sensor.md @@ -45,6 +45,8 @@ Create the subscription template and publish it. curl -iX POST "${BROKER_URL}/v2/entities" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "id": "urn:ngsi-ld:LocationSensor:001", "type": "LocationSensor", @@ -64,6 +66,8 @@ curl -iX POST "${BROKER_URL}/v2/entities" \ curl -iX PATCH \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:LocationSensor:001/attrs" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -H "Content-Type: application/json" \ -d '{ "location": { @@ -85,5 +89,7 @@ within the project boundary. ```bash curl -iX DELETE \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:LocationSensor:001" \ - -H "Authorization: Bearer ${BROKER_TOKEN}" + -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" ``` diff --git a/doc/examples/temperature_sensor.md b/doc/examples/temperature_sensor.md index 0b42936..dae68af 100644 --- a/doc/examples/temperature_sensor.md +++ b/doc/examples/temperature_sensor.md @@ -46,6 +46,8 @@ Create the subscription template and publish it. curl -iX POST "${BROKER_URL}/v2/entities" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "id": "urn:ngsi-ld:TemperatureSensor:001", "type": "TemperatureSensor", @@ -58,6 +60,8 @@ curl -iX POST "${BROKER_URL}/v2/entities" \ curl -iX POST "${BROKER_URL}/v2/entities" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "id": "urn:ngsi-ld:TemperatureSensor:002", "type": "TemperatureSensor", @@ -75,9 +79,11 @@ curl -iX PATCH \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:001/attrs" \ -H "Content-Type: application/json" \ -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" \ -d '{ "temperature": { - "value": 28.0, + "value": 38.5, "type": "Number" } }' @@ -88,8 +94,13 @@ curl -iX PATCH \ ```bash curl -iX DELETE \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:001" \ - -H "Authorization: Bearer ${BROKER_TOKEN}" + -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" + curl -iX DELETE \ "${BROKER_URL}/v2/entities/urn:ngsi-ld:TemperatureSensor:002" \ - -H "Authorization: Bearer ${BROKER_TOKEN}" + -H "Authorization: Bearer ${BROKER_TOKEN}" \ + -H "Fiware-Service: ${FIWARE_SERVICE}" \ + -H "Fiware-ServicePath: ${FIWARE_SERVICEPATH}" ``` diff --git a/doc/index.md b/doc/index.md index 99fd7ba..9b96191 100644 --- a/doc/index.md +++ b/doc/index.md @@ -37,12 +37,15 @@ To allow **public** access to NGSI-LD context documents, it's necessary to grant For all examples, the following environment variables are used: ```bash -export BROKER_URL="http://your_broker:1026" +export BROKER_URL=http://your_broker:1026 +export BROKER_TOKEN=your_token +export FIWARE_SERVICE=your_service +export FIWARE_SERVICEPATH=your_servicepath ``` -Replace `your_broker_url` with the actual URL of your FIWARE broker. After -running this command, the BROKER_URL environment variable will be -available to all subsequent commands in the same terminal session. +Alternatively, you can use `.env` files to set these variables. +Copy the `.env.example` file to `.env` and set the values accordingly. +Then run `source .env` to load the environment variables. ### General FIWARE Broker Commands diff --git a/doc/scripts/delete_all_subscriptions.sh b/doc/scripts/delete_all_subscriptions.sh index 85e8c21..9e77938 100755 --- a/doc/scripts/delete_all_subscriptions.sh +++ b/doc/scripts/delete_all_subscriptions.sh @@ -12,6 +12,15 @@ if [ -n "$BROKER_TOKEN" ]; then HEADERS+=(-H "Authorization: Bearer $BROKER_TOKEN") fi +# Check if FIWARE_SERVICE and FIWARE_SERVICEPATH are provided +if [ -z "$FIWARE_SERVICE" ]; then + HEADERS+=(-H "Fiware-Service: $FIWARE_SERVICE") +fi + +if [ -z "$FIWARE_SERVICEPATH" ]; then + HEADERS+=(-H "Fiware-ServicePath: $FIWARE_SERVICEPATH") +fi + # Fetch all subscription IDs using a GET request response=$(curl -s -o /dev/null -w "%{http_code}" -X GET "${BROKER_URL}/v2/subscriptions" "${HEADERS[@]}") http_code="$response" diff --git a/doc/scripts/register_all_subscriptions.sh b/doc/scripts/register_all_subscriptions.sh index e64501b..38d8860 100755 --- a/doc/scripts/register_all_subscriptions.sh +++ b/doc/scripts/register_all_subscriptions.sh @@ -21,6 +21,15 @@ if [ -n "$BROKER_TOKEN" ]; then HEADERS+=(-H "Authorization: Bearer $BROKER_TOKEN") fi +# Check if FIWARE_SERVICE and FIWARE_SERVICEPATH are provided +if [ -z "$FIWARE_SERVICE" ]; then + HEADERS+=(-H "Fiware-Service: $FIWARE_SERVICE") +fi + +if [ -z "$FIWARE_SERVICEPATH" ]; then + HEADERS+=(-H "Fiware-ServicePath: $FIWARE_SERVICEPATH") +fi + # Fetch all subscriptions using a GET request response=$(curl -s -o /dev/null -w "%{http_code}" -X GET "${BROKER_URL}/v2/subscriptions" "${HEADERS[@]}") http_code="$response" diff --git a/doc/subscription_template.md b/doc/subscription_template.md index 20a1fd5..1a59d9b 100644 --- a/doc/subscription_template.md +++ b/doc/subscription_template.md @@ -57,7 +57,8 @@ subscription, including entities, attributes, and (geospatial) queries. all or none of the following fields: - **Georel**: Set the geospatial relationship (e.g., `near;maxDistance:1000`). - **Geometry**: Choose the geometry type (e.g., `Point`). - - **Coordinates**: Enter the coordinates for the geospatial query. + - **Coordinates**: Enter the coordinates (`latitude`, + `longitude`) for the geospatial query (e.g. `34.751,135.22;34.67,135.221;34.671,135.345;34.752,135.344;34.751,135.22`). - **Insert project boundary**: Automatically insert the project boundary as valid geospatial query.