diff --git a/FIWARE CRUD Operations.postman_collection.json b/FIWARE CRUD Operations.postman_collection.json index 728df0b..1d45c52 100644 --- a/FIWARE CRUD Operations.postman_collection.json +++ b/FIWARE CRUD Operations.postman_collection.json @@ -2,7 +2,7 @@ "info": { "_postman_id": "35d014dc-aa73-4424-8307-2e177af64f2a", "name": "FIWARE CRUD Operations", - "description": "This tutorial builds on the data created in the previous [stock management example](http://fiware.github.io/tutorials.Entity-Relationships/) and introduces the concept of [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete), allowing users to manipulate the data held within the context.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.CRUD-Operations/icon/GitHub-Mark-32px.png) [FIWARE 103: Manipulating Context Data through CRUD Operations ](https://github.com/Fiware/tutorials.CRUD-Operations)\n\n# Data Entities\n\nWithin the FIWARE platform, an entity represents the state of a physical or\nconceptual object which exists in the real world.\n\n## Entities within a stock management system\n\nWithin our simple stock management system, we currently have four entity types.\nThe relationships between our entities are defined as shown below:\n\n![](https://fiware.github.io/tutorials.Entity-Relationships/img/entities.png)\n\n- A **Store** is a real world bricks and mortar building. Stores would have\n properties such as:\n - Store name, e.g. \"Checkpoint Markt\"\n - Address, e.g. \"Friedrichstraße 44, 10969 Kreuzberg, Berlin\"\n - Physical location, e.g. _52.5075 N, 13.3903 E_\n- A **Shelf** is a real world object to hold items which we wish to sell.\n Each shelf would have properties such as:\n - Shelf name, e.g. \"Wall Unit\"\n - Physical location, e.g. _52.5075 N, 13.3903 E_\n - Maximum capacity\n - An association to the store in which the shelf is located\n- A **Product** is defined as something that we sell - it is a conceptual\n object. Products would have properties such as:\n - Product name, e.g. \"Melons\"\n - Price, e.g. 13.99 Euros\n - Size, e.g. Small\n- An **Inventory Item** is another conceptual entity, used to associate\n products, stores, shelves and physical objects. It would have properties\n such as:\n - An association to the product being sold\n - An association to the store in which the product is being sold\n - An association to the shelf where the product is being displayed\n - Stock count, i.e. product quantity available in the warehouse\n - Shelf count, i.e. number of items available on the shelf\n\nAs you can see, each of the entities defined above contain some properties which\nare liable to change. For example, product price could change, stock could be sold\nand the number of items on the shelves would drop.\n\n# Architecture\n\nThis application will only make use of one FIWARE component - the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/). Using\nthe Orion Context Broker is sufficient for an application to qualify as\n_“Powered by FIWARE”_.\n\nCurrently, the Orion Context Broker relies on open source\n[MongoDB](https://www.mongodb.com/) technology to store the context data it\nmanages. Therefore, the architecture will consist of two components:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/)\n which will receive requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n- The underlying [MongoDB](https://www.mongodb.com/) database:\n - Used by the Orion Context Broker to store context information such\n as data entities, subscriptions and registrations\n\nSince the two components interact by means of HTTP requests, they can be\ncontainerized and run from exposed ports.\n\n![](https://fiware.github.io/tutorials.CRUD-Operations/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of\nthe associated `docker-compose.yml` file:\n\n```yaml\norion:\n image: quay.io/fiware/orion:latest\n hostname: orion\n container_name: orion\n depends_on:\n - mongo-db\n networks:\n - default\n expose:\n - \"1026\"\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --bind_ip_all --smallfiles\n```\n\nBoth containers reside on the same network - the Orion Context Broker is\nlistening on port `1026` and MongoDB is listening on the default port `271071`.\nFor the sake of this tutorial, we have also made the two ports available from\noutside the network so that cUrl or Postman can access them without having to\nbe run from inside the network. The command-line initialization should be self\nexplanatory.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple both components will be run using\n[Docker](https://www.docker.com). **Docker** is a container technology which\nallows to package each component with its environment and run it in isolation.\n\n- To install Docker on Windows follow the instructions\n [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions\n [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions\n [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker\napplications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Entity-Relationships/master/docker-compose.yml)\nis used configure the required services for the application. This means all\ncontainer services can be brought up with a single command. Docker Compose is\ninstalled by default as part of Docker for Windows and Docker for Mac, however\nLinux users will need to follow the instructions found\n[here](https://docs.docker.com/compose/install/)\n\nYou can check your current **Docker** and **Docker Compose** versions using the\nfollowing commands:\n\n```console\ndocker-compose -v\ndocker version\n```\n\nPlease ensure that you are using Docker version 20.10 or higher and Docker\nCompose 1.21 or higher and upgrade if necessary.\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should\ndownload the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line\nfunctionality similar to a Linux distribution on Windows.\n\n# Start Up\n\nAll services can be initialised from the command-line by running the bash script\nprovided within the repository. Please clone the repository and create the\nnecessary images by running the commands as shown below:\n\n```console\ngit clone git@github.com:Fiware/tutorials.CRUD-Operations.git\ncd tutorials.CRUD-Operations\n\n./services start\n```\n\nThis command will also import seed data from the previous\n[Store Finder tutorial](https://github.com/Fiware/tutorials.Entity-Relationships)\non startup.\n\n> :information_source: **Note:** If you want to clean up and start over again\n> you can do so with the following command:\n>\n> ```console\n> ./services stop\n> ```\n\n# What is CRUD?\n\n**Create**, **Read**, **Update** and **Delete** are the four basic functions of\npersistent storage. These operations are usually referred to using the acronym\n**CRUD**. Within a database each of these operations map directly to a series of\ncommands, however their relationship with a RESTful API is slightly more complex.\n\nThe [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) uses\n[NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) to manipulate the\ncontext data. As a RESTful API, requests to manipulate the data held within the\ncontext follow the standard conventions found when mapping HTTP verbs to CRUD\noperations.\n\n## Entity CRUD Operations\n\nFor operations where the `` is not yet known within the context, or\nis unspecified, the `/v2/entities` endpoint is used.\n\nOnce an `` is known within the context, individual data entities can\nbe manipulated using the `/v2/entities/` endpoint.\n\nIt is recommended that entity identifiers should be URNs following the\n[NGSI-LD guidelines](https://docbox.etsi.org/ISG/CIM/Open/ISG_CIM_NGSI-LD_API_Draft_for_public_review.pdf),\ntherefore each `id` is a URN which follows a standard format:\n`urn:ngsi-ld::`. This helps making every `id` in the\ncontext data unique.\n\n| HTTP Verb | `/v2/entities` | `/v2/entities/` |\n| ---------- | :--------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: |\n| **POST** | CREATE a new entity and add to the context. | CREATE or UPDATE an attribute of a specified entity. |\n| **GET** | READ entity data from the context. This will return data from multiple entities. The data can be filtered. | READ entity data from a specified entity. This will return data from a single entity only. The data can be filtered. |\n| **PUT** | :x: | :x: |\n| **PATCH** | :x: | :x: |\n| **DELETE** | :x: | DELETE an entity from the context |\n\nA complete list of entity endpoints can be found in the\n[NGSI v2 Swagger Specification](https://fiware.github.io/specifications/OpenAPI/ngsiv2#/Entities)\n\n## Attribute CRUD Operations\n\nTo perform CRUD operations on attributes, the `` must be known. Each\nattribute is effectively a key-value pair.\n\nThere are three endpoints:\n\n- `/v2/entities//attrs` is only used for a patch operation to\n update one or more exisiting attributes.\n- `/v2/entities//attrs/` is used to manipulate an\n attribute as a whole.\n- `/v2/entities//attrs//value` is used to read or update\n the `value` of an attribute, leaving the `type` untouched.\n\n| HTTP Verb | `.../attrs` | `.../attrs/` | `.../attrs//value` |\n| ----------- | :-------------------------------------------------------------: | :---------------------------------------------------: | :--------------------------------------------------------------------------------------: |\n| **POST** | :x: | :x: | :x: |\n| **GET** | :x: | :x: | READ the value of an attribute from a specified entity. This will return a single field. |\n| **PUT** | :x: | :x: | UPDATE the value of single attribute from a specified entity. |\n| **PATCH** | UPDATE one or more existing attributes from an existing entity. | :x: | :x: |\n| **DELETE**. | :x: | DELETE an existing attribute from an existing entity. | :x: |\n\nA complete list of attribute endpoints can be found in the\n[NGSI v2 Swagger Specification](https://fiware.github.io/specifications/OpenAPI/ngsiv2#/Attributes)\n\n## Batch CRUD Operations\n\nAdditionally the Orion Context Broker has a convenience batch operation endpoint\n`/v2/op/update` to manipulate multiple entities in a single operation.\n\nBatch operations are always triggered by a POST request where the payload is an\nobject with two properties:\n\n- `actionType` specifies the kind of action to invoke (e.g. `delete`)\n- `entities` is an array of objects holding the list of entities to update, along\n with the relevant entity data used to perform the operation.\n", + "description": "This tutorial builds on the data created in the previous [stock management example](http://fiware.github.io/tutorials.Entity-Relationships/) and introduces the concept of [CRUD operations](https://en.wikipedia.org/wiki/Create,_read,_update_and_delete), allowing users to manipulate the data held within the context.\n\nThe `docker-compose` file for this tutorial can be found on GitHub: \n\n![GitHub](https://fiware.github.io/tutorials.CRUD-Operations/icon/GitHub-Mark-32px.png) [FIWARE 103: Manipulating Context Data through CRUD Operations ](https://github.com/Fiware/tutorials.CRUD-Operations)\n\n# Data Entities\n\nWithin the FIWARE platform, an entity represents the state of a physical or\nconceptual object which exists in the real world.\n\n## Entities within a stock management system\n\nWithin our simple stock management system, we currently have four entity types.\nThe relationships between our entities are defined as shown below:\n\n![](https://fiware.github.io/tutorials.Entity-Relationships/img/entities.png)\n\n- A **Store** is a real world bricks and mortar building. Stores would have\n properties such as:\n - Store name, e.g. \"Checkpoint Markt\"\n - Address, e.g. \"Friedrichstraße 44, 10969 Kreuzberg, Berlin\"\n - Physical location, e.g. _52.5075 N, 13.3903 E_\n- A **Shelf** is a real world object to hold items which we wish to sell.\n Each shelf would have properties such as:\n - Shelf name, e.g. \"Wall Unit\"\n - Physical location, e.g. _52.5075 N, 13.3903 E_\n - Maximum capacity\n - An association to the store in which the shelf is located\n- A **Product** is defined as something that we sell - it is a conceptual\n object. Products would have properties such as:\n - Product name, e.g. \"Melons\"\n - Price, e.g. 13.99 Euros\n - Size, e.g. Small\n- An **Inventory Item** is another conceptual entity, used to associate\n products, stores, shelves and physical objects. It would have properties\n such as:\n - An association to the product being sold\n - An association to the store in which the product is being sold\n - An association to the shelf where the product is being displayed\n - Stock count, i.e. product quantity available in the warehouse\n - Shelf count, i.e. number of items available on the shelf\n\nAs you can see, each of the entities defined above contain some properties which\nare liable to change. For example, product price could change, stock could be sold\nand the number of items on the shelves would drop.\n\n# Architecture\n\nThis application will only make use of one FIWARE component - the\n[Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/). Using\nthe Orion Context Broker is sufficient for an application to qualify as\n_“Powered by FIWARE”_.\n\nCurrently, the Orion Context Broker relies on open source\n[MongoDB](https://www.mongodb.com/) technology to store the context data it\nmanages. Therefore, the architecture will consist of two components:\n\n- The [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/)\n which will receive requests using\n [NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2)\n- The underlying [MongoDB](https://www.mongodb.com/) database:\n - Used by the Orion Context Broker to store context information such\n as data entities, subscriptions and registrations\n\nSince the two components interact by means of HTTP requests, they can be\ncontainerized and run from exposed ports.\n\n![](https://fiware.github.io/tutorials.CRUD-Operations/img/architecture.png)\n\nThe necessary configuration information can be seen in the services section of\nthe associated `docker-compose.yml` file:\n\n```yaml\norion:\n image: quay.io/fiware/orion:latest\n hostname: orion\n container_name: orion\n depends_on:\n - mongo-db\n networks:\n - default\n expose:\n - \"1026\"\n ports:\n - \"1026:1026\"\n command: -dbhost mongo-db -logLevel DEBUG\n```\n\n```yaml\nmongo-db:\n image: mongo:3.6\n hostname: mongo-db\n container_name: db-mongo\n expose:\n - \"27017\"\n ports:\n - \"27017:27017\"\n networks:\n - default\n command: --bind_ip_all --smallfiles\n```\n\nBoth containers reside on the same network - the Orion Context Broker is\nlistening on port `1026` and MongoDB is listening on the default port `271071`.\nFor the sake of this tutorial, we have also made the two ports available from\noutside the network so that cUrl or Postman can access them without having to\nbe run from inside the network. The command-line initialization should be self\nexplanatory.\n\n# Prerequisites\n\n## Docker\n\nTo keep things simple both components will be run using\n[Docker](https://www.docker.com). **Docker** is a container technology which\nallows to package each component with its environment and run it in isolation.\n\n- To install Docker on Windows follow the instructions\n [here](https://docs.docker.com/docker-for-windows/)\n- To install Docker on Mac follow the instructions\n [here](https://docs.docker.com/docker-for-mac/)\n- To install Docker on Linux follow the instructions\n [here](https://docs.docker.com/install/)\n\n**Docker Compose** is a tool for defining and running multi-container Docker\napplications. A\n[YAML file](https://raw.githubusercontent.com/Fiware/tutorials.Entity-Relationships/master/docker-compose.yml)\nis used configure the required services for the application. This means all\ncontainer services can be brought up with a single command. Docker Compose is\ninstalled by default as part of Docker for Windows and Docker for Mac, however\nLinux users will need to follow the instructions found\n[here](https://docs.docker.com/compose/install/)\n\nYou can check your current **Docker** and **Docker Compose** versions using the\nfollowing commands:\n\n```console\ndocker-compose -v\ndocker version\n```\n\nPlease ensure that you are using Docker version 24.0.x or higher and Docker\nCompose 1.21 or higher and upgrade if necessary.\n\n## WSL\n\nWe will start up our services using a simple bash script. Windows users should\ndownload the [Windows Subsystem for Linux](https://learn.microsoft.com/en-us/windows/wsl/install) to provide a command-line\nfunctionality similar to a Linux distribution on Windows.\n\n# Start Up\n\nAll services can be initialised from the command-line by running the bash script\nprovided within the repository. Please clone the repository and create the\nnecessary images by running the commands as shown below:\n\n```console\ngit clone git@github.com:Fiware/tutorials.CRUD-Operations.git\ncd tutorials.CRUD-Operations\n\n./services start\n```\n\nThis command will also import seed data from the previous\n[Store Finder tutorial](https://github.com/Fiware/tutorials.Entity-Relationships)\non startup.\n\n> :information_source: **Note:** If you want to clean up and start over again\n> you can do so with the following command:\n>\n> ```console\n> ./services stop\n> ```\n\n# What is CRUD?\n\n**Create**, **Read**, **Update** and **Delete** are the four basic functions of\npersistent storage. These operations are usually referred to using the acronym\n**CRUD**. Within a database each of these operations map directly to a series of\ncommands, however their relationship with a RESTful API is slightly more complex.\n\nThe [Orion Context Broker](https://fiware-orion.readthedocs.io/en/latest/) uses\n[NGSI](https://fiware.github.io/specifications/OpenAPI/ngsiv2) to manipulate the\ncontext data. As a RESTful API, requests to manipulate the data held within the\ncontext follow the standard conventions found when mapping HTTP verbs to CRUD\noperations.\n\n## Entity CRUD Operations\n\nFor operations where the `` is not yet known within the context, or\nis unspecified, the `/v2/entities` endpoint is used.\n\nOnce an `` is known within the context, individual data entities can\nbe manipulated using the `/v2/entities/` endpoint.\n\nIt is recommended that entity identifiers should be URNs following the\n[NGSI-LD guidelines](https://docbox.etsi.org/ISG/CIM/Open/ISG_CIM_NGSI-LD_API_Draft_for_public_review.pdf),\ntherefore each `id` is a URN which follows a standard format:\n`urn:ngsi-ld::`. This helps making every `id` in the\ncontext data unique.\n\n| HTTP Verb | `/v2/entities` | `/v2/entities/` |\n| ---------- | :--------------------------------------------------------------------------------------------------------: | :------------------------------------------------------------------------------------------------------------------: |\n| **POST** | CREATE a new entity and add to the context. | CREATE or UPDATE an attribute of a specified entity. |\n| **GET** | READ entity data from the context. This will return data from multiple entities. The data can be filtered. | READ entity data from a specified entity. This will return data from a single entity only. The data can be filtered. |\n| **PUT** | :x: | :x: |\n| **PATCH** | :x: | :x: |\n| **DELETE** | :x: | DELETE an entity from the context |\n\nA complete list of entity endpoints can be found in the\n[NGSI v2 Swagger Specification](https://fiware.github.io/specifications/OpenAPI/ngsiv2#/Entities)\n\n## Attribute CRUD Operations\n\nTo perform CRUD operations on attributes, the `` must be known. Each\nattribute is effectively a key-value pair.\n\nThere are three endpoints:\n\n- `/v2/entities//attrs` is only used for a patch operation to\n update one or more exisiting attributes.\n- `/v2/entities//attrs/` is used to manipulate an\n attribute as a whole.\n- `/v2/entities//attrs//value` is used to read or update\n the `value` of an attribute, leaving the `type` untouched.\n\n| HTTP Verb | `.../attrs` | `.../attrs/` | `.../attrs//value` |\n| ----------- | :-------------------------------------------------------------: | :---------------------------------------------------: | :--------------------------------------------------------------------------------------: |\n| **POST** | :x: | :x: | :x: |\n| **GET** | :x: | :x: | READ the value of an attribute from a specified entity. This will return a single field. |\n| **PUT** | :x: | :x: | UPDATE the value of single attribute from a specified entity. |\n| **PATCH** | UPDATE one or more existing attributes from an existing entity. | :x: | :x: |\n| **DELETE**. | :x: | DELETE an existing attribute from an existing entity. | :x: |\n\nA complete list of attribute endpoints can be found in the\n[NGSI v2 Swagger Specification](https://fiware.github.io/specifications/OpenAPI/ngsiv2#/Attributes)\n\n## Batch CRUD Operations\n\nAdditionally the Orion Context Broker has a convenience batch operation endpoint\n`/v2/op/update` to manipulate multiple entities in a single operation.\n\nBatch operations are always triggered by a POST request where the payload is an\nobject with two properties:\n\n- `actionType` specifies the kind of action to invoke (e.g. `delete`)\n- `entities` is an array of objects holding the list of entities to update, along\n with the relevant entity data used to perform the operation.\n", "schema": "https://schema.getpostman.com/json/collection/v2.1.0/collection.json" }, "item": [ diff --git a/README.ja.md b/README.ja.md index 284f394..56d3c3d 100644 --- a/README.ja.md +++ b/README.ja.md @@ -223,7 +223,7 @@ docker-compose -v docker version ``` -Docker バージョン 20.10 以降と Docker Compose 1.29 以上を使用していることを確認 +Docker バージョン 24.0.x 以降と Docker Compose 2.24.x 以上を使用していることを確認 し、必要に応じてアップグレードしてください。 ## WSL diff --git a/README.md b/README.md index 05f437f..ab4201d 100644 --- a/README.md +++ b/README.md @@ -186,7 +186,7 @@ docker-compose -v docker version ``` -Please ensure that you are using Docker version 20.10 or higher and Docker Compose 1.29 or higher and upgrade if +Please ensure that you are using Docker version 24.0.x or higher and Docker Compose 2.24.x or higher and upgrade if necessary. ## WSL