外部サービスデータを取得します

マーケットプレイスの主な担当者は、マーケットプレイスの外部プロキシサービス (マーケットプレイス ePS) を使用して、 REST API または AWS S3 バケットなどの外部サービス (ExtSvc) に HTTP リクエストを実行できます。 リクエストは、請求のためにテクニカルアカウントを介して認証、処理、記録され、外部サービスにリダイレクトされます。 外部サービスからの応答は、外部サービスを直接呼び出す場合と同じ HTTP 応答コードと同じ応答ヘッダーを使用して、元の形式で受信されます。 外部サービスがエラーで失敗すると、元の形式でこのエラーが表示されます。

外部 REST API をリクエストします

マーケットプレイスの EPS トンネルへのコールを正常に送信するには、外部サービスプロバイダの API のドキュメントを参照してください。

一般的なワークフローには、次の手順が含まれます。

  1. 一覧表に記載されている外部サービスプロバイダのドキュメントに従って、GETPOSTPUT、またはDELETEの方法を使用します。

  2. p.hereapi.com/tunnel/ ドキュメントに記載されているエンドポイント URL よりも前に使用してください。 一般的なリクエスト URL の構造は次のとおりです。

   https://p.hereapi.com/tunnel/{domain}/{pathToExternalServiceResource}?{optionalRequestParameters}
  • p.hereapi.com - ベース URL
  • {domain} - HTTP 要求を転送するための ExtSvc ドメイン ( 識別子 )
  • {pathToExternalServiceResource} - ドメインと結合する ExtSvc リソースパス
  • {optionalRequestParameters} - ExtSvc リソースに必要なすべてのリクエストパラメータ
  1. 外部サービスプロバイダのドキュメントに記載されているように、クエリーパラメータ、ヘッダー、およびリクエスト本文を入力します。

  2. 認証には HERE platform Bearer トークンを使用し、外部サービスプロバイダのドキュメントに記載されている認証プロトコルは無視してください。 マーケットプレイスの EPS が、お客様の認証と承認を処理します。

  1. 上記の形式を使用して、外部 REST API にリクエストを投稿します。 たとえば、 https://p.hereapi.com/tunnel/dataservice.company-name.com/locations/v1/topcities/50です。 この通話には、 HERE アカウントの資格情報を使用します。

    サブスクリプションの詳細ページで、 API エンドポイントの例で、リクエストのドメインとリソースのパスを探します。

    HERE Marketplace での外部 REST API データサブスクリプション
    図 1. HERE Marketplace での外部 REST API データサブスクリプション

    リソースパスの末尾にアスタリスク(ワイルドカード)がある場合は、スラッシュの後にパスの詳細を追加できます。 ただし、リクエストの URL にはアスタリスクを付けないでください。

    リソースパスの変更の可能性およびオプションのリクエストパラメータについては、サービスプロバイダの対応するサブスクリプションの情報を参照してください。

  2. マーケットプレイスの EPS dataservice.company-name.com は、ユーザーを認証し、サービスプロバイダドメインとも呼ばれる部品を検査して、この以前にプロビジョニングされたドメインを検証します。

  3. マーケットプレイス EPS locations/v1/topcities/50 は、サービスプロバイダリソースとも呼ばれるパーツを検査し、指定されたドメイン内でこのリソースへのアクセス権があるかどうかを確認します。 アクセス権がない場合は、エラーが返されます。 アクセス権を持っている場合は、手順 4 に従います。
  4. マーケットプレイスの EPS https://dataservice.company-name.com/locations/v1/topcities50では、ドメインとパスを組み合わせて、リクエストの実行準備を行います。 同時に、マーケットプレイスの EPS は、データベースに保存されているマーケットプレイスプロバイダの API キー を抽出し、リクエストに追加します ( 単純な API キーベースの認証の場合 ) 。 たとえば、以前にプロビジョニングされた API キー がABCDEFGHの場合 、結果の要求はhttps://dataservice.company-name.com/locations/v1/topcities/50?api_key=ABCDEFGHになります。
  5. リクエストが実行され、レスポンスが読み取られます。
  6. 適切な請求とアナリティクスを実行するために、応答が記録され、テクニカルアカウントに送信されます。 これはバックグラウンドでの操作であり、コールの遅延には影響しません。
  7. 元のペイロードと HTTP ヘッダーを使用して、応答が返信されます。 失敗した場合は、エラーペイロードを含む HTTP 応答コードが返されます。

外部 AWS S3 バケットをリクエストします

マーケットプレイスのコアサービスとして、マーケットプレイスの外部プロキシサービスを使用して、 Amazon ( AWS ) S3 バケットにクラウドオブジェクトとして保存されている外部リソースを要求できます。 次の形式で、バケット全体またはその特定のディレクトリに要求を作成します。

バケットリソース全体
特定のバケットディレクトリリソース
GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources
GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources?path={somePath}
  • p.hereapi.com - ベース URL
  • {bucketName} - S3 バケット名 ( 識別子 )
  • {somePath} - リソースパス :
    • dir_1/
    • dir_1/sub_dir_1/

一般的なワークフローには、次の手順が含まれます。

  1. 上記の形式を使用して、外部の AWS S3 バケットにリクエストを投稿します。 たとえば、 https://p.hereapi.com/aws/s3/buckets/s3extproxytest/resources?path=dir_1/です。 この通話には、 HERE アカウントの資格情報を使用します。

    サブスクリプションの詳細ページの API エンドポイントの例で、リクエストの S3 バケット名とリソースパスを探します。

    HERE Marketplace の外部 AWS S3 データサブスクリプション
    図 2. HERE Marketplace の外部 AWS S3 データサブスクリプション

    リソースパスの末尾にアスタリスク(ワイルドカード)がある場合は、スラッシュの後にパスの詳細を追加できます。 ただし、リクエストの URL にはアスタリスクを付けないでください。

    リソースパスの変更の詳細については、対応するサブスクリプションのサービスプロバイダによる情報を参照してください。

  2. ダウンロードするオブジェクトのリストを含む応答が返されます。

    応答の例 :

    Status code 200
    

    本文 :

    バケットリソース全体
    特定のバケットディレクトリリソース
    {
              "pageId": 0,
              "nextPageId": 0,
              "isNextPage": false,
              "objectsCount": 1,
              "subDirectories": [
              {
                  "key": "dir_1/",
                  "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/"
              },
              {
                  "key": "dir_2/",
                  "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_2/"
              },
              {
                  "key": "dir_3/",
                  "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_3/"
              },
              {
                  "key": "dir_4/",
                  "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_4/"
              },
              {
                  "key": "dir_5/",
                  "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources?path=dir_5/"
              }
              ],
              "directoryContent": [
              {
              "bucketName": "s3extproxytest",
              "key": "TEST",
              "resourceApiUrl": "/aws/s3/buckets/s3extproxytest/resources/object?path=TEST",
              "size": 57,
              "lastModified": "2021-02-25T17:05:40.000+00:00"
              }
              ]
          }
    {
            "pageId": 0,
            "nextPageId": 0,
            "isNextPage": false,
            "objectsCount": 3,
            "subDirectories": [
            {
                "key" : "dir_1/subdir_1/",
                "directoryApiUrl" : "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/subdir_1/"
            },
            {
                "key" : "dir_1/subdir_2/",
                "directoryApiUrl" : "/aws/s3/buckets/s3extproxytest/resources?path=dir_1/subdir_2/"
            }
            ],
            "directoryContent": [
            {
                "bucketName" : "s3extproxytest",
                "key" : "dir_1/0a415506de72cde298f0f85b0a60bb9e1cd09dba.jpg",
                "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/0a415506de72cde298f0f85b0a60bb9e1cd09dba.jpg",
                "size" : 1292159,
                "lastModified" : "2021-03-01T16:07:36.000+00:00"
            },
            {
                "bucketName" : "s3extproxytest",
                "key" : "dir_1/13136c8506f89055fd05ec441855f8af9431c966.jpg",
                "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/13136c8506f89055fd05ec441855f8af9431c966.jpg",
                "size" : 147628,
                "lastModified" : "2021-03-01T16:07:51.000+00:00"
            },
            {
                "bucketName" : "s3extproxytest",
                "key" : "dir_1/14ec91f6eac37c60c3b5e6198910d2bef55f65dd.jpg",
                "resourceApiUrl" : "/aws/s3/buckets/s3extproxytest/resources/object?path=dir_1/14ec91f6eac37c60c3b5e6198910d2bef55f65dd.jpg",
                "size" : 383339,
                "lastModified" : "2021-03-01T16:07:45.000+00:00"
            }
            ]
        }
    • resourceApiUrl - ダウンロードする現在のディレクトリ内のオブジェクト ( ファイル ) のリスト
  3. リソースリクエストのオブジェクトのリストで提供されているオブジェクト URL を指定して、ダウンロードするオブジェクトをリクエストします。 次の形式を使用します。

    GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources/object?path={somePath}
    
  4. オブジェクトをダウンロードするための署名済みの URL が提供されます。

    応答の例 :

    Status code 200
    

    本文 :

    https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/?x-consumer-id=null&  X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210603T125418Z&X-Amz-SignedHeaders=host&  X-Amz-Expires=3599&  X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210603%2Feu-central-1%2Fs3%2Faws4_request&  X-Amz-Signature=46e3ba3f84a1d4628fd7fa987e935250263fdd2e410ad70f805115430bcc5d13
    

    この単一のリクエストを使用して、上記の手順をスキップし、すべての含まれているオブジェクトへの署名済みの URL を即座に取得することもできます。

    GET https://p.hereapi.com/aws/s3/buckets/{bucketName}/resources/directory?path={somePath}
    

    応答の例 :

    Status code 200
    

    本文 :

     {
         "pageId" : 0 ,
         "nextPageId" : 0 ,
         "isNextPage" : false ,
         "objectsCount" : 3 ,
         "subDirectories": [
         {
             "key": "dir_1/subdir_1/",
             "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources/directory?path=dir_1/subdir_1/"
         },
         {
             "key": "dir_1/subdir_2/",
             "directoryApiUrl": "/aws/s3/buckets/s3extproxytest/resources/directory?path=dir_1/subdir_2/"
         }
         ],
         "signedUrls": {                 
             "dir_1/7648dd3581b8dc9d920d12bf8b85fa29465d1d28.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/7648dd3581b8dc9d920d12bf8b85fa29465d1d28.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=36cdb3f1297ed964536916b928046897b9f18008537247a597e8e5e951d5b461",
             "dir_1/de60a0fff76f28918ab764d7417fa0db724da22f.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/de60a0fff76f28918ab764d7417fa0db724da22f.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=55deb0fca00d6e1dc39f1dd5b454db78ced661e79985e70ece4afd538d6db529",
             "dir_1/9fdb285d503ce28c87901666c18a2583143f5e6d.jpg": "https://s3extproxytest.s3.eu-central-1.amazonaws.com/dir_1/9fdb285d503ce28c87901666c18a2583143f5e6d.jpg?x-consumer-id=HERE&X-Amz-Algorithm=AWS4-HMAC-SHA256&X-Amz-Date=20210913T104444Z&X-Amz-SignedHeaders=host&X-Amz-Expires=3600&X-Amz-Credential=AKIAXGEF5U6TPFKR4FEI%2F20210913%2Feu-central-1%2Fs3%2Faws4_request&X-Amz-Signature=e2d5d88930ac6d9aefd0053a98c06b54c35cc407625e8ea88db2e08dd64a5fc4"
         }
     }
    
  5. または、オブジェクトをダウンロードするために署名済みの URL を要求する場合、一時的なセキュリティ資格情報に、 AWS CLI または AWS API を使用して AWS リソースに対する要求を作成するよう要求できます。次の形式を使用します。

    GET https://p.hereapi.com//aws/s3/buckets/{bucketName}/credentials
    

    応答の例 :

       {
           "accessKeyId": "ASIAXGEF5U6TGQBTBEG3",
           "secretAccessKey": "Aweqo1WiZc8q5z4qTFtgSwnAkf1bltaE8/TI+ypy",
           "sessionToken": "FwoGZXIvYXdzEFgaDPmnt1gHSnE7jTR+EiKfAhnqCapu+Eu0nBK3+7oH2ycukTl5x47pOd1IRrM0qAVjLhzXV0DoW0wseD22C12Ce/       Bs6tApl9nLuuCcoOqL75lZKc7lmiojFxTKeTIn8SjCXCjxmJYrlFLCk6m0VcqfkW0ERzgyY0pmEsH2Ry2+oPEoxjbBLlZQS3T7ghKpzwuQW5GJfLAs2RSR/       9n3PZnOXyz9a6uWEmiCwAqXNEqiTKOEkfW0/+Fm1RBOtCN7+r+nmL+1S15JfNaM/PYYOTR9inxO0j4cCqJaxVsm2WOSSBktolexYXPdsvDnrP9/WXKTUP/nSwb+ilr6ZIAhSvA8GuMD2IMgjXUBuVVWFf4fIHMcCYld4SYYJYcQua/AHCxuI6XutQsQePw29i8ZokxQKNa8jIcGMin8dq00FYwK5kqjTc5tjP5sS8NykwkTEN4zq0Azd9wn2NsclzMGRutkww==",
           "expiresInSeconds": 3600
       }
    
  6. 誤った資格情報を使用した場合、または要求されたリソースにサブスクライブしていない場合は、エラーの説明とともに応答が失敗します。

    誤った許可トークンの場合の応答例 :

    Status code 401
    

    本文 :

       {
           "error": "Unauthorized",
           "error_description": "Token Validation Failure - Unable to verify signature segment"
       }
    

    リソースへのアクセス権がない場合の応答例 :

    Status code 403
    

    本文 :

       {
           "title": "Error accessing extsvc resource",
           "code": "E504014",
           "errorCause": "User {userId} does not have readResource permissions on extsvc resource   hrn:here-dev:extsvc::{​​​realm}​​​:{bucketName}-​​​{somePath}​​​",
           "action": "Verify user has policy/permissions granted via ExtSvc Marketplace   subscriptions",
           "errorTag": "extsvc_resource_forbidden"
       }
    

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

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