이 페이지는 Cloud Translation API를 통해 번역되었습니다.

실시간 업데이트

RTU는 긴급 폐쇄 또는 주기적으로 변경되는 메타데이터 (예: 도착예정시간)와 같이 예측할 수 없는 업데이트에 주로 사용됩니다. 변경사항을 즉시 반영할 필요가 없는 경우 대신 일괄 피드 처리를 사용할 수 있습니다. 실시간 업데이트는 5분 이내에 처리됩니다.

Google Cloud Platform 설정

GCP 프로젝트를 설정합니다. RTU API에 액세스하려면 GCP 프로젝트가 필요합니다.
- 편집자 액세스 권한을 부여합니다. food-support@google.com
- Google 실무담당자에게 GCP 프로젝트 번호를 알립니다.실시간 업데이트가 작동하려면 GCP 프로젝트를 Actions Center 계정과 연결해야 합니다.
- Maps Booking API 사용 설정:
  - GCP에서 API 및 서비스 > Library로 구성됩니다.
  - 'Google Maps Booking API'를 검색합니다. <ph type="x-smartling-placeholder">
    </ph>
  - 샌드박스 인스턴스('Google Maps Booking API (Dev)')를 찾아 사용 설정을 클릭합니다.
  - 프로덕션 인스턴스('Google Maps Booking API')를 찾아 사용 설정을 클릭합니다. <ph type="x-smartling-placeholder">
    </ph>
  - GCP 프로젝트에 대한 편집자 역할이 있는 서비스 계정을 만듭니다. 자세한 내용은 서비스 계정 설정을 참고하세요.
  - 실시간 업데이트를 작업 중인 환경에 일괄 피드를 업로드해야 합니다.
  - API 인증을 위해 원하는 언어로 Google 클라이언트 라이브러리를 설치하는 것이 좋습니다. OAuth 범위로 'https://www.googleapis.com/auth/mapsbooking'을 사용합니다. 아래에 포함된 코드 샘플은 이러한 라이브러리를 사용합니다. 그렇지 않으면 OAuth 2.0을 사용하여 Google API에 액세스하기에 설명된 대로 토큰 교환을 수동으로 처리해야 합니다.

서비스 계정 설정

실시간 업데이트 API와 같은 인증된 HTTPS를 Google API에 요청하려면 서비스 계정이 필요합니다.

서비스 계정을 설정하려면 다음 안내를 따르세요.

Google Cloud Platform 콘솔에 액세스합니다.
Actions Center의 계정에도 연결된 Google Cloud 프로젝트가 있습니다. 해당 프로젝트를 선택합니다(아직 선택하지 않은 경우).
왼쪽 메뉴에서 서비스 계정을 클릭합니다.
서비스 계정 만들기를 클릭합니다.
서비스 계정의 이름을 입력하고 만들기를 클릭합니다.
역할 선택에서 프로젝트 > 편집기에서 사용할 수 있습니다.
계속을 클릭합니다.
선택사항: 서비스 계정에 대한 액세스 권한을 부여할 사용자를 추가하고 완료를 클릭합니다.
더보기를 클릭합니다. > 키 만들기를 선택합니다.
형식으로 JSON을 선택하고 만들기를 클릭합니다.
새 공개/비공개 키 쌍이 생성되면 머신에 다운로드합니다.

API 작업

실시간 업데이트 API는 업데이트와 삭제라는 두 가지 유형의 작업을 지원합니다. 실시간 업데이트 API를 통한 새 항목 추가는 지원되지 않습니다. 단일 API 요청에 여러 업데이트를 포함하는 경우 실시간 업데이트를 일괄 처리할 수 있습니다. 단일 API 호출로 최대 1,000개의 업데이트를 일괄 처리할 수 있습니다. 가능하다면 빈도 기반 방식 (즉, X분마다 시스템에 변경사항 확인)보다는 트리거 기반 접근 방식을 사용하여 RTU를 통해 업데이트를 전송하는 것이 좋습니다 (즉, 시스템에서 데이터가 변경되면 Google에 실시간 업데이트가 트리거됨).

실시간 업데이트 API는 샌드박스와 프로덕션 환경 모두에서 작동합니다. 샌드박스 환경은 API 요청 및 프로덕션 환경을 테스트하여 주문 엔드 투 엔드 사용자에게 표시되는 콘텐츠를 업데이트하는 데 사용됩니다.

샌드박스 - partnerdev-mapsbooking.googleapis.com
프로덕션 - mapsbooking.googleapis.com

엔드포인트

실시간 업데이트 API는 두 개의 엔드포인트를 노출하여 인벤토리 업데이트에 대한 수신 요청을 처리합니다.

업데이트 - /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
삭제 - /v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete

PARTNER_ID 매개변수는 아래 스크린샷과 같이 계정 및 사용자 페이지의 작업 센터에서 확인할 수 있습니다.

위 스크린샷에서 PARTNER_ID 값을 예로 들어 10000001을 사용할 경우 샌드박스 및 프로덕션에서 API 요청을 보내기 위한 전체 URL은 아래 예와 같이 표시됩니다.

샌드박스 업데이트

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

샌드박스 삭제

https://partnerdev-mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

프로덕션 업데이트

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchPush

프로덕션 삭제

https://mapsbooking.googleapis.com/v1alpha/inventory/partners/10000001/feeds/google.food_service/record:batchDelete

항목 업데이트

인벤토리의 항목을 업데이트하려면 HTTP POST 요청에서 update 엔드포인트를 사용합니다. 각 POST 요청에는 업데이트하려는 항목이 포함된 JSON 페이로드와 함께 10000001 매개변수가 포함되어야 합니다.

참고: 일일 데이터 피드에도 실시간 업데이트 API를 통해 제출된 변경사항이 포함되어야 합니다. 그렇지 않으면 데이터가 오래되었거나 오래된 것일 수 있습니다.

업데이트 요청 페이로드

요청 본문은 레코드 목록이 포함된 JSON 객체입니다. 각 레코드는 업데이트 중인 항목에 해당합니다. proto_record 필드와 항목 업데이트 시간을 나타내는 generation_timestamp로 구성됩니다.

  {
    "records": [
      {
        "proto_record":"ServiceData PROTO",
        "generation_timestamp":"UPDATE_TIMESTAMP"
      }
    ]
  }

ServiceData PROTO: 업데이트할 ServiceData 항목의 proto 또는 JSON 변환입니다.
UPDATE_TIMESTAMP: 백엔드 시스템에서 항목이 생성된 시점의 타임스탬프를 포함해야 합니다. 이 필드가 포함되지 않으면 Google이 요청을 수신한 시간으로 설정됩니다. batchPush 요청을 통해 항목을 업데이트할 때 generation_timestamp 필드는 항목 버전 관리에 사용됩니다. 관계형 인벤토리 스키마에서 시간 값의 예상 형식을 확인하세요.

페이로드 본문의 크기는 5MB를 초과할 수 없습니다.
공백을 제거하여 크기를 줄입니다.
batchPush 요청에는 최대 1,000개의 업데이트가 있을 수 있습니다.

예

도착예정시간 업데이트

배송 서비스의 도착예정시간을 30~60분에서 60~90분으로 긴급하게 업데이트해야 한다고 가정해 보겠습니다. 업데이트에는 전체 서비스 항목의 JSON이 포함되어야 합니다.

다음과 같은 서비스 항목을 생각해 보세요.

{
	"service": {
		"service_id": "service/entity002",
		"service_type": "DELIVERY",
		"parent_entity_id": "entity002",
		"lead_time": {
			"min_lead_time_duration": "600s",
			"max_lead_time_duration": "1800s"
		},
		"action_link_id": "delivery_link/entity002"
	}
}

HTTP POST에 의한 실시간 업데이트는 다음과 같습니다 (요청 본문은 가독성을 위해 예쁘게 인쇄됩니다).

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery",
        "service_type" : "DELIVERY",
        "parent_entity_id" : "23456",
        "disabled" : "false",
        "action_link_id": "delivery_link/entity002",
        "lead_time" : {
          "min_lead_time_duration" : {
            "seconds": "3600"
          },
          "max_lead_time_duration" : {
            "seconds": "5400"
          }
        }
      }
    },
    "generation_timestamp": "2023-09-13T17:11:10.750Z"
  }]
}

여러 항목 업데이트

단일 API 호출로 여러 식당 항목을 업데이트하려면 요청 본문의 proto_record 필드에 여러 레코드를 포함합니다.

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchPush
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery",
        "service_type" : "DELIVERY",
        "parent_entity_id" : "23456",
        "disabled" : "false",
        "action_link_id": "delivery_link/entity002",
        "lead_time" : {
          "min_lead_time_duration" : {
            "seconds": "1800"
          },
          "max_lead_time_duration" : {
            "seconds": "3600"
          }
        }
      }
    },
    "generation_timestamp": "2023-09-13T17:11:10.750Z"
  },
  {
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "fee" : {
        "fee_id" : "12345/delivery_fee",
        "fee_type" : "DELIVERY",
        "fixed_amount" : {
          "currency_code" : "USD",
          "units" : "10",
          "nanos" : "0"
        },
        "service_ids": ["service/entity002"]
      }
    },
    "generation_timestamp" : "2023-09-13T17:11:10.750Z"
  }]
}

항목 삭제

인벤토리에서 항목을 삭제하려면 HTTP POST 요청에서 DELETE 엔드포인트를 사용하세요. 각 POST 요청에는 삭제할 항목의 식별자가 포함된 JSON 페이로드와 함께 PARTNER_ID 매개변수가 포함되어야 합니다.

참고: 일일 데이터 피드에도 실시간 업데이트 API를 통해 제출된 변경사항이 포함되어야 합니다. 그렇지 않으면 일일 일괄 수집이 실시간 변경사항을 덮어씁니다.

POST v1alpha/inventory/partners/PARTNER_ID/feeds/google.food_service/record:batchDelete
Host: mapsbooking.googleapis.com
Content-Type: application/json
{
  "records": [{
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "service" : {
        "service_id" : "23456/delivery"
      }
    },
    "delete_time": "2023-09-13T17:11:10.750Z"
  },
  {
    "proto_record": {
      "@type": "type.googleapis.com/food.ordering.service.v1.ServiceData",
      "fee" : {
        "fee_id" : "12345/delivery_fee"
     }
  },
  "delete_time" : "2023-09-13T17:11:10.750Z"
  }]
}

항목 추가

데이터 불일치가 발생할 수 있으므로 실시간 업데이트를 사용하여 새 항목을 추가하지 마세요. 대신 일괄 피드를 사용하세요.

검증 및 API 응답 코드

실시간 업데이트 API 호출에 대해 수행되는 두 가지 유형의 유효성 검사가 있습니다.

요청 수준: 이 유효성 검사는 페이로드가 스키마를 따르고 모든 proto_record에 id 및 type 필드가 포함되어 있는지 확인합니다. 이러한 검사는 동기식이며 결과는 API 응답 본문에 반환됩니다. 응답 코드 200과 빈 JSON 본문 {}는 이러한 유효성 검사가 통과되었으며 요청의 항목이 처리 대기열에 추가되었음을 의미합니다. 200이 아닌 응답 코드는 이러한 유효성 검사 중 하나 이상이 실패하고 전체 요청이 거부되었음을 의미합니다 (페이로드의 모든 항목 포함). 예를 들어 proto_record에 @type가 누락된 경우 다음과 같은 오류 응답이 반환됩니다.

  {
      "error": {
        "code": 400,
    "message": "Record:{...}",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.DebugInfo",
        "detail": "[ORIGINAL ERROR] generic::invalid_argument: Failed to parse one or more rtu records. Record:... The entity type could not be extracted from the entity value." 
      }
    ]
  }

항목 수준: 페이로드의 각 항목 (proto_record)은 스키마를 기준으로 유효성이 검사됩니다. 이 유효성 검사 단계에서 발생하는 문제는 API 응답에서 보고되지 않습니다. 이러한 신고는 작업 센터의 RTU 신고 대시보드에만 보고됩니다.

참고: 200 응답 코드가 모든 항목이 성공적으로 처리되었다는 의미는 아닙니다.

API 할당량

실시간 API 업데이트의 할당량은 60초마다 요청 1,500개(평균 초당 요청 25개)입니다. 할당량을 초과하면 Google에서 다음과 같은 오류 메시지를 반환합니다.

{
  "error": {
    "code": 429,
    "message": "Insufficient tokens for quota ...",
    "status": "RESOURCE_EXHAUSTED",
    "details": [...]
  }
}

이 문제를 처리하려면 성공할 때까지 기하급수적으로 큰 간격으로 호출을 다시 시도하세요. 정기적으로 할당량을 소진하는 경우 API 요청 하나에 더 많은 항목을 포함해 보세요. API 호출 한 번에 최대 1,000개의 항목을 포함할 수 있습니다.

처리 시간 실시간 업데이트

실시간 업데이트를 통해 업데이트된 항목은 5분 이내에 처리됩니다.

전환 추적