拠点
listingsapi-js SDKを使用して、ビジネスの拠点の一覧取得、検索、作成、更新、アーカイブを行います。
拠点は Listings API の中心となるエンティティであり、すべての掲載情報、レビュー、分析レコード、投稿はそれぞれ1つの拠点に紐づきます。拠点に関するすべてのメソッドは、ListingsAPI クライアントインスタンスで使用できます。
fetchAllLocations
カーソルベースのページネーションを使用して、アカウント内の拠点を一覧表示します。locations、pageInfo、success、および raw API ペイロードを含むオブジェクトを返します。fetchAll: true を指定すると、自動でページネーションを処理し、代わりにフラットな Location[] を返します。
// Single pageconst page = await client.fetchAllLocations({ first: 25 });if (!Array.isArray(page)) {console.log(page.locations); // Location[]console.log(page.pageInfo); // { hasNextPage, hasPreviousPage, startCursor, endCursor, total? } // Next pageconst next = await client.fetchAllLocations({ first: 25, after: page.pageInfo.endCursor!,});} // All pages at once, returns Location[]const all = await client.fetchAllLocations({ fetchAll: true, pageSize: 100 });オプション
fetchLocationsByIds
ID を指定して特定の拠点を取得します。数値 ID または base64 エンコードされた ID を受け取り、フラットな Location[] を返します。入力配列が空の場合は、リクエストを送信せずに [] を返します。
const locations = await client.fetchLocationsByIds([16808, 16809, 'TG9jYXRpb246MTY4MTA=']);console.log(locations); // Location[]fetchLocationsByStoreCodes
指定された店舗コードに一致する拠点を取得します。フラットな Location[] を返し、入力配列が空の場合はリクエストを送信せずに [] を返します。
const locations = await client.fetchLocationsByStoreCodes(['AD-SF-001', 'AD-NY-001']);searchLocations
名前、住所、店舗 ID を対象に、キーワードで拠点を検索します。fetchAllLocations と同じページネーション形式で結果を返し、fetchAll にも同様に対応しています。
// Single pageconst result = await client.searchLocations('Brooklyn', { first: 20 });if (!Array.isArray(result)) {console.log(result.locations, result.pageInfo);} // All matching results, returns Location[]const all = await client.searchLocations('Brooklyn', { fetchAll: true }); // Restrict which fields are searchedconst byName = await client.searchLocations('Acme Dental', { fields: ['name'] });オプション
fetchAllLocations のすべてのページネーションオプションに加え、次のオプションを使用できます。
createLocation
新しい拠点を作成します。API では、name、200文字以上の description、subCategoryId、countryIso、city が必須です。作成された拠点を含むレスポンスペイロードを返しますが、API が入力を拒否した場合は、代わりにクライアントが ValidationError をスローするため、確認する成功フラグはありません。
const result = await client.createLocation({name: 'Acme Dental',description: 'Acme Dental is a family-owned dental practice offering cleanings, ' + 'checkups, fillings, crowns, and cosmetic dentistry for patients of all ' + 'ages. Our gentle, experienced team uses modern digital imaging and ' + 'same-day scheduling to make every visit fast and comfortable.',subCategoryId: 1432,countryIso: 'US',city: 'San Francisco',street: '2100 Mission St',stateIso: 'CA',postalCode: '94110',phone: '4155550100',storeId: 'AD-SF-003',});console.log(result.location.id);updateLocation
既存の拠点の1つ以上のフィールドを更新します。拠点の id と、変更するフィールドを渡します。数値 ID は自動でエンコードされます。
await client.updateLocation({id: 16808,phone: '4155550199',name: 'Acme Dental Mission District',});archiveLocations
1つ以上の拠点をアーカイブします。アーカイブされた拠点は、ディレクトリへの同期が停止します。
await client.archiveLocations([16808, 16809]);cancelArchiveLocations
指定された拠点のアーカイブ予定を取り消します。拠点 ID、selectionType、changedBy 識別子を位置引数として受け取ります。
await client.cancelArchiveLocations([16808],'manual', // selectionType'ops@example.com', // changedBy);ID のエンコード
拠点に関するすべてのメソッドは、数値 ID または base64 エンコードされた ID を受け取ります。SDK は数値 ID（および数値文字列）を Location:<id> 形式で自動的にエンコードし、すでにエンコードされている値はそのまま渡します。
// These are equivalentawait client.fetchLocationsByIds([16808]);await client.fetchLocationsByIds(['TG9jYXRpb246MTY4MDg=']);エンコードされた形式を直接使用する必要がある場合に備えて、エンコーダーもエクスポートされています。
import { encodeLocationId } from 'listingsapi-js'; encodeLocationId(16808); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('16808'); // 'TG9jYXRpb246MTY4MDg='encodeLocationId('TG9jYXRpb246MTY4MDg='); // unchanged