기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

# 주소 양식 SDK
<a name="address-form-sdk"></a>

Address Form SDK는 스마트 주소 입력 양식 구축을 간소화합니다. SDK로 빌드된 주소 양식은 사용자가 입력을 시작할 때 관련 주소 제안을 제공합니다. 사용자가 제안을 선택하면 주소 양식이 도시, 주, 우편 번호와 같은 필드를 자동으로 채웁니다. 이렇게 하면 수동 입력을 최소화하여 오류를 줄이고 데이터 입력 속도를 높일 수 있습니다. 또한 사용자는 맵에서 선택한 주소를 미리 보고 위치 핀을 조정하여 특정 입구 또는 픽업 위치를 표시할 수 있으므로 정확도가 크게 향상됩니다.

![자동 완성 기능을 보여주는 Address Form SDK 데모](http://docs.aws.amazon.com/ko_kr/location/latest/developerguide/images/address-form-demo.gif)


## 사용해 보기
<a name="address-form-try-it"></a>

### 데모
<a name="address-form-demo"></a>

완전한 기능을 갖춘 [주소 양식 데모](https://aws-geospatial.github.io/address-form-sdk-js/)를 사용해 보세요.

### 직접 빌드
<a name="address-form-builder"></a>

[시작하기](#address-form-getting-started) 로 이동하여 주소 양식 SDK를 사용하여 주소 양식 구현을 시작하거나이 SDK로 구동되고 [https://console.aws.amazon.com/location/](https://console.aws.amazon.com/location/) Amazon Location Service 콘솔에서 액세스할 수 있는 Location Service의 WYSIWYG [주소 양식 빌더 마법사](https://console.aws.amazon.com/location/solution-builder/home#/address-form)를 사용하여 코드 없는 접근 방식을 시도합니다. 이 대화형 마법사를 사용하면 예측 제안, 자동 필드 모집단 및 유연한 레이아웃을 사용하여 사용자 지정 양식을 생성할 수 있습니다. 개발자는 코드를 작성하지 않고도 쉽게 통합할 수 있도록 ready-to-use 수 있는 패키지를 React JavaScript, React TypeScript 또는 독립 실행형 HTML/JavaScript로 다운로드할 수 있습니다.

## 주요 기능
<a name="address-form-features"></a>

Address Form SDK의 주요 기능은 다음과 같습니다.
+ 주소 및 POIs에 대한 기본 제공 형식 미리 제안을 제공하여 데이터 입력 속도를 높입니다.
+ 보다 정확한 결과를 위해 구성 가능한 장소 유형 검색(예: 우편 번호, 지역)을 활성화합니다.
+ 사용자가 현재 영역을 빠르게 중앙에 배치할 수 있도록 자동 브라우저 위치 감지 기능을 제공합니다.
+ 명확성과 컨텍스트를 높이기 위해 내장 맵 시각화를 표시합니다.
+ 시스템에서 제공한 위치를 잃지 않고 맵에서 주소 위치를 조정할 수 있으므로 정확도와 제어가 모두 보장됩니다.
+ 코딩이 필요 없는 WYSIWYG 빌더 도구가 포함되어 있어 시간과 노력을 절약할 수 있습니다.
+ 미리 입력 APIs에 대한 디바운싱 및 캐싱을 구현하여 성능을 최적화하고 비용을 절감합니다.
+ 애플리케이션의 브랜드 및 사용자 경험에 맞게 스타일 사용자 지정을 지원합니다.

다음 Amazon Location Service API 작업을 사용하여 주소 양식에 주소 정보를 제공합니다.

**[GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html)**  
대화형 맵을 렌더링하기 위한 맵 타일을 검색하여 주소의 위치를 시각화하고 주소의 위치를 조정합니다.

**[Autocomplete](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html)**  
실시간 주소 제안을 사용자 유형으로 제공합니다.

**[Suggest](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html)**  
실시간 주소 및 POI 제안을 사용자 유형으로 제공합니다.

**[ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html)**  
현재 위치에 따라 주소를 자동으로 채우도록 선택한 경우 사용자의 현재 위치를 가장 가까운 알려진 주소 주소로 변환합니다.

**[GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html)**  
자동 완성 또는 제안 API의 결과에서 주소를 선택한 후 선택한 주소에 대한 자세한 장소 정보를 검색합니다.

## 가격 책정
<a name="address-form-pricing"></a>

SDK는 Apache-2.0 라이선스에 따라 무료 [오픈 소스](https://github.com/aws-geospatial/address-form-sdk-js)입니다. API 사용량에 대해서만 비용을 지불합니다. [Amazon Location Service 요금 페이지를](https://aws.amazon.com/location/pricing/) 참조하세요.

## 시작하기
<a name="address-form-getting-started"></a>

주소 양식 SDK는 React 앱 또는 독립 실행형 HTML 및 JavaScript 페이지에서 사용할 수 있습니다. 아래 지침에 따라 시작합니다.

### 사전 조건
<a name="address-form-prerequisites"></a>

**참고**  
주소 양식 SDK가 제대로 작동하려면 필요한 권한이 있는 API 키가 필요합니다. Amazon Location Service 콘솔의 [Address Form SDK Builder 마법사](https://console.aws.amazon.com/location/solution-builder/home#/address-form)를 사용하여 다음 권한을 가진 API 키를 생성하거나 아래 지침에 따라 수동으로 생성합니다.

주소 양식 SDK를 사용하려면 API 키 정책에서 다음 작업을 허용해야 합니다.
+ `geo-maps:GetTile` - 맵 구성 요소를 표시할 때 필요합니다. [GetTile](https://docs.aws.amazon.com/location/latest/APIReference/API_geomaps_GetTile.html) API 참조를 참조하세요.
+ `geo-places:Autocomplete` - 미리 입력 기능에 `Autocomplete` 작업을 사용할 때 필요합니다. [자동 완성](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Autocomplete.html) API 참조를 참조하세요.
+ `geo-places:Suggest` - 미리 입력 기능에 `Suggest` 작업을 사용할 때 필요합니다. [제안](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_Suggest.html) API 참조를 참조하세요.
+ `geo-places:ReverseGeocode` - 사용자가 브라우저의 지리적 위치 API를 사용하여 현재 위치를 제공하도록 허용할 때 필요합니다. [ReverseGeocode](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_ReverseGeocode.html) API 참조를 참조하세요.
+ `geo-places:GetPlace` - 미리 입력 기능을 사용할 때 필요합니다. [GetPlace](https://docs.aws.amazon.com/location/latest/APIReference/API_geoplaces_GetPlace.html) API 참조를 참조하세요.

[API 키를 사용하여 인증](https://docs.aws.amazon.com/location/latest/developerguide/using-apikeys.html) 가이드에 따라 필요한 권한이 있는 Amazon Location Service API 키를 생성합니다.

필요한 권한이 있는 [CreateKey](https://docs.aws.amazon.com/location/latest/APIReference/API_geotags_CreateKey.html) API의 키 정책 예제:

#### 주소 양식 권한에 대한 CreateKey 요청
<a name="createkey-example"></a>

```
{
  "KeyName": "ExampleKey",
  "ExpireTime": "YYYY-MM-DDThh:mm:ss.sss",
  "Restrictions": {
    "AllowActions": [
      "geo-maps:GetTile",
      "geo-places:Autocomplete",
      "geo-places:Suggest",
      "geo-places:GetPlace",
      "geo-places:ReverseGeocode"
    ],
    "AllowResources": [
      "arn:aws:geo-maps:<Region>::provider/default",
      "arn:aws:geo-places:<Region>::provider/default"
    ]
  }
}
```

### 설치
<a name="address-form-installation"></a>

#### HTML/JavaScript
<a name="address-form-html-js-install"></a>

HTML 코드에 SDK에 대한 다음 CSS 및 JavaScript 포함

```
...
<head>
...
<link
rel="stylesheet"
href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
/>
...
</head>
...
<body>
...
<script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"></script>
</body>
...
```

#### React
<a name="address-form-react-install"></a>

npm에서 SDK를 설치합니다. `npm install @aws/address-form-sdk-js` 

### SDK 사용
<a name="address-form-use-sdk"></a>

React 앱에 다음 코드를 추가합니다. API 키 `AMAZON_LOCATION_API_KEY` 및 API 키가 생성된 리전`AMAZON_LOCATION_REGION`으로를 업데이트합니다. 양식이 제출되면 `onSubmit` 콜백은 `getData` 비동기 함수를 제공합니다. 이 함수를 `intendedUse` 값으로 호출하여 양식 데이터를 검색합니다.

```
onSubmit: async (getData) => {
  const data = await getData({
    intendedUse: "SingleUse", // or "Storage"
  });
};
```

**참고**  
결과를 저장하거나 캐싱해야 하는 `"Storage"` 경우를 사용합니다. 이렇게 하면 Amazon Location Service[의 용도 요구 사항을](https://docs.aws.amazon.com/location/latest/developerguide/places-intended-use.html) 준수할 수 있습니다.

------
#### [ HTML/JavaScript ]

```
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Address Form</title>
    <link
      rel="stylesheet"
      href="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.css"
    />
  </head>
  <body>
    <form
      id="amazon-location-address-form"
      class="address-form flex-row flex-1"
    >
      <div class="flex-column">
        <input
          data-type="address-form"
          name="addressLineOne"
          data-api-name="suggest"
          data-show-current-location="true"
        />
        <input data-type="address-form" name="addressLineTwo" />
        <input data-type="address-form" name="city" />
        <input data-type="address-form" name="province" />
        <input data-type="address-form" name="postalCode" />
        <input data-type="address-form" name="country" />
        <div class="flex-row">
          <button data-type="address-form" type="submit">Submit</button>
          <button data-type="address-form" type="reset">Reset</button>
        </div>
      </div>
      <div data-type="address-form" data-map-style="Standard,Light"></div>
    </form>
    <></script>
script src="https://cdn.jsdelivr.net/npm/@aws/address-form-sdk-js/dist/standalone/address-form-sdk.umd.js"
    <script>
      AddressFormSDK.render({
        root: "#amazon-location-address-form",
        apiKey: "AMAZON_LOCATION_API_KEY",
        region: "AMAZON_LOCATION_REGION",
        showCurrentCountryResultsOnly: true,
        onSubmit: async (getData) => {
          // Get form data with intendedUse parameter
          // Use "SingleUse" for one-time display only
          // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
          const data = await getData({ intendedUse: "SingleUse" });
          console.log(data);
        },
      });
    </script>
  </body>
</html>
```

------
#### [ React ]

```
import React from 'react';
import { AddressForm, Flex } from "@aws/address-form-sdk-js";

export default function App() {
  return (
    <AddressForm
      apiKey="AMAZON_LOCATION_API_KEY"
      region="AMAZON_LOCATION_REGION"
      onSubmit={async (getData) => {
        // Get form data with intendedUse parameter
        // Use "SingleUse" for one-time display only
        // Use "Storage" if you plan to store/cache the results - makes an extra API call to grant storage rights
        const data = await getData({ intendedUse: "SingleUse" });
        console.log(data);
      }}
    >
      <Flex
        direction="row"
        flex
      >
        <Flex direction="column">
          <input
            data-api-name="autocomplete"
            data-type="address-form"
            name="addressLineOne"
            placeholder="Enter address"
          />
          <input
            data-type="address-form"
            name="addressLineTwo"
          />
          <input
            data-type="address-form"
            name="city"
            placeholder="City"
          />
          <input
            data-type="address-form"
            name="province"
            placeholder="State/Province"
          />
          <input
            data-type="address-form"
            name="postalCode"
          />
          <input
            data-type="address-form"
            name="country"
            placeholder="Country"
          />
          <Flex direction="row">
            <button address-form="submit">
              Submit
            </button>
            <button address-form="reset">
              Reset
            </button>
          </Flex>
        </Flex>
        <AddressFormMap
          mapStyle={[
            'Standard',
            'Light'
          ]}
         />
      </Flex>
    </AddressForm>
  );
}
```

------

## 지원되는 국가
<a name="address-form-supported-countries"></a>

주소 양식 SDK는 Amazon Location Service를 사용하여 전역적으로 주소 자동 채우기를 지원합니다. 다음 국가는 주소 필드 구문 분석을 완벽하게 지원합니다. 여기서 각 주소 구성 요소는 해당 필드에 채워집니다.
+ 오스트레일리아(AU)
+ 캐나다(CA)
+ 프랑스(FR)
+ 홍콩(HK)
+ 아일랜드(IE)
+ 뉴질랜드(NZ)
+ 필리핀(PH)
+ 싱가포르(SG)
+ 영국(GB)
+ 미국(US)

다른 모든 국가는 미리 보기 상태입니다. 미리 보기 국가는 국가별 형식 없이 `addressLineOne` 필드에 전체 주소를 표시합니다. 향후 릴리스는 이러한 동작을 개선하고 최신 버전의 SDK를 사용하여 이러한 개선 사항에 액세스할 수 있습니다.

## 지원되는 AWS 리전
<a name="address-form-supported-aws-regions"></a>

Address Form SDK 및 Address Form Builder 마법사는 API `Current` 버전을 사용하여 Amazon Location Service가 운영되는 모든 AWS 리전에서 사용할 수 APIs. [Amazon Location 지원 리전에서 지원되는 리전](https://docs.aws.amazon.com/location/latest/developerguide/location-regions.html)의 전체 목록을 봅니다.

## API 참조
<a name="address-form-api-reference"></a>

[README API 참조를 참조하세요](https://github.com/aws-geospatial/address-form-sdk-js#api-reference).