出荷を作成する

このチュートリアルでは、タンペレから出発し、ヘルシンキを経由してベルリンブランデンブルクに陸路で向かう出荷を作成します。ルートに沿って更新されるETA予測を取得します。

前提条件

ユーザーをログインする

ユーザーをログインします。これにより、ユーザーアクセストークンuserTokenが返されます。このトークンは後のリクエストに必要です。

ジオフェンスを作成する

タンペレピルカラ空港、ヘルシンキ空港、ベルリンブランデンブルク空港の3つのジオフェンスを作成します。

ジオフェンスを作成するには、geofencesエンドポイントにリクエストを送信します。

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Tampere–Pirkkala Airport",
        "description":"Area around Tampere–Pirkkala airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "61.415278",
                "lng": "23.587778"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "7d5ef384-a0bb-4c32-a0f2-d6ee2b761483"
}

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Helsinki Airport",
        "description":"Area around Helsinki airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "60.317222",
                "lng": "24.963333"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "6e551fae-2687-11ec-af55-00155ddd7ddb"
}

curl -X POST \
    'https://{tcHost}/geofences/v2' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Berlin Brandenburg airport",
        "description":"Area around Berlin Brandenburg airport",
        "type":"circle",
        "definition": {
            "center": {
                "lat": "52.366667",
                "lng": "13.503333"
            },
            "radius": 3000
        }
    }'

{
  "message": "created",
  "id": "c20df606-281d-11ec-90fc-00155ddd7ddb"
}

場所を作成する

タンペレピルカラ空港、ヘルシンキ空港、ベルリンブランデンブルク空港の3つの場所を作成し、前のセクションで作成したジオフェンスを対応する場所に割り当てます。場所を作成するには、locationsエンドポイントにリクエストを送信します。

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Tampere–Pirkkala airport"
        "description":"Tampere–Pirkkala airport"
        "location": {
            "lat": "61.415278",
            "lng": "23.587778"
        },
        "address": {
            "street":"Tornikaari 50",
            "city":"Pirkkala",
            "postalCode":"33960",
            "country":"Finland"
        },
        "geofenceId":"7d5ef384-a0bb-4c32-a0f2-d6ee2b761483"
    }'

{
  "locationId": "LOC-f79d965d-9124-446d-b0b4-f71ae793f602"
}

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Helsinki airport"
        "description":"Helsinki airport"
        "location": {
            "lat": "60.317222",
            "lng": "24.963333"
        },
        "address": {
            "street":"Lentoasemantie 1",
            "city":"Vantaa",
            "postalCode":"01530",
            "country":"Finland"
        },
        "geofenceId":"6e551fae-2687-11ec-af55-00155ddd7ddb"
    }'

{
  "locationId": "LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb"
}

curl -X POST \
    'https://{tcHost}/locations/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"Berlin Brandenburg airport"
        "description":"Berlin Brandenburg airport"
        "location": {
            "lat": "52.366667",
            "lng": "13.503333"
        },
        "address": {
            "street":"Willy-Brandt-Platz",
            "city":"Schönefeld",
            "postalCode":"12529",
            "country":"Germany"
        },
        "geofenceId":"c20df606-281d-11ec-90fc-00155ddd7ddb"
    }'

{
  "locationId": "LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb"
}

出荷を作成する

出荷を作成し、その出荷のセグメントに場所を割り当てます。trackingIdは出荷のすべてのセグメントに割り当てられている、登録済みのデバイスを参照します。場所がジオフェンスにすでに割り当てられており、デバイスがセグメントに割り当てられているため、セグメントの状態の遷移が自動化されます。autoStartがtrueに設定されているため、デバイスが出荷の出発地に対応する最初の場所のジオフェンスを離れると、出荷が開始されるように設定されます。出荷の交通機関モードは道路である点に注意してください ("transportMode":"truck"プロパティで示されています)。出荷を作成するには、shipmentsエンドポイントにリクエストを送信します。

curl -X POST \
    'https://{tcHost}/shipments/v4' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "name":"From Tampere-Pirkkala to Berlin Brandenburg",
        "description":"A shipment from the Tampere-Pirkkala airport to the Berlin Brandenburg airport",
        "autoStart": "true",
        "segments": [
            {
                "name":"From Tampere-Pirkkala to Helsinki",
                "description":"Origin of the shipment",
                "transportMode":"truck",
                "trackingId":"{trackingId}",
                "origin":"LOC-f79d965d-9124-446d-b0b4-f71ae793f602",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "providedEtd":"2021-10-01T06:30:00Z",
                "providedEta":"2021-10-01T07:30:00Z"
            },
            {
                "name":"Dwelling at Helsinki",
                "description":"Waypoint of the shipment where shipment dwells",
                "transportMode":"undefined",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "providedEtd":"2021-10-01T06:30:00Z",
                "providedEta":"2021-10-01T22:45:00Z"
            },
            {
                "name":"From Helsinki to Brandenburg",
                "description":"Destination of the shipment",
                "transportMode":"truck",
                "trackingId":"{trackingId}",
                "origin":"LOC-7e814132-2821-11ec-ba1d-00155ddd7ddb",
                "destination":"LOC-878c8e9e-2821-11ec-8fc2-00155ddd7ddb",
                "providedEtd":"2021-10-01T22:45:00Z",
                "providedEta":"2021-10-02T01:15:00Z"
            }
        ],
        "providedEtd":"2021-10-01T06:30:00Z",
        "providedEta":"2021-10-02T01:15:00Z"
    }'

{
  "shipmentId": "SHP-a79ee6bf-436c-4684-9be6-48b084a94228"
}

出荷の詳細とETAの予測を取得する

出荷の詳細と予測ETAを取得するには、Get shipment details API呼び出しを使用します。予測ETAはcalculatedEta出荷プロパティで定義される出荷全体と、calculatedEtdとcalculatedEtaセグメントプロパティで定義される各出荷セグメントでそれぞれ利用できます。

出荷から出荷計画を作成する

出荷は新しい出荷を作成できる出荷計画に変換することもできます。

curl -X POST \
    'https://{tcHost}/shipments/v4/plans' \
    -H 'Content-Type: application/json' \
    -H 'Authorization: Bearer {userToken}' \
    -d '{
        "shipmentId":"SHP-a79ee6bf-436c-4684-9be6-48b084a94228"
    }'

{
  "shipmentPlanId": "SHPP-736b28d4-2836-11ec-91b6-00155ddd7ddb"
}

作成された出荷は、Shipment Tracking Webから利用できます。