Yerel sipariş karşılama uygulamasını kullanma

Yerel sipariş karşılamayı desteklemek için şu akıllı ev niyetlerini işleyecek bir uygulama oluşturmanız gerekir:

• IDENTIFY: Yerel olarak kontrol edilebilir akıllı cihazların bulunmasını destekler. Amaç işleyici, keşif sırasında akıllı cihazınızın döndürdüğü verileri çıkarır ve Google'a yanıt olarak gönderir.
• EXECUTE: Komutların yürütülmesini destekler.
• QUERY: Cihaz durumunu sorgulamayı destekler.
• REACHABLE_DEVICES: (İsteğe bağlı) Bir merkez (veya köprü) cihazının arkasından yerel olarak kontrol edilebilen bitiş cihazlarının bulunmasını destekler.

Bu uygulama kullanıcının Google Home veya Google Nest cihazlarında çalışır ve akıllı cihazınızı Asistan'a bağlar. Uygulamayı TypeScript (tercih edilen) veya JavaScript kullanarak oluşturabilirsiniz.

TypeScript, uygulamanızın döndürdüğü verilerin platformun beklediği türlerle eşleştiğinden statik olarak emin olmak için bağlamalardan yararlanabileceğiniz için önerilir.

API hakkında daha fazla bilgi için Local Home SDK API referansı sayfasına bakın.

Aşağıdaki snippet'ler, yerel sipariş karşılama uygulamasını nasıl başlatabileceğinizi ve işleyicilerinizi nasıl ekleyebileceğinizi gösterir.

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

import App = smarthome.App;
const localHomeApp: App = new App("1.0.0");
localHomeApp
  .onIdentify(identifyHandler)
  .onReachableDevices(reachableDevicesHandler)
  .onExecute(executeHandler)
  .listen()
  .then(() => {
    console.log("Ready");
  });

Projenizi oluşturun

Yerel sipariş karşılama uygulamanızı dağıtmak istiyorsanız kodunuz ve tüm bağımlıları için bir JavaScript paketi oluşturmanız gerekir.

Tercih ettiğiniz paketleyici yapılandırmasıyla uygun proje yapısını önyüklemek için yerel sipariş karşılama projesi başlatıcısını kullanın.

Proje şablonları

Paketleyici yapılandırmanızı seçmek için npm init komutunu aşağıdaki örneklerde gösterildiği gibi çalıştırın:

npm init @google/local-home-app project-directory/ --bundler none

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

npm init @google/local-home-app project-directory/ --bundler webpack

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── webpack.config.web.js
├── webpack.config.node.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler rollup

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
├── rollup.config.js
└── serve.js

npm init @google/local-home-app project-directory/ --bundler parcel

project-directory/
├── node_modules/
├── package.json
├── .gitignore
├── index.ts
├── test.ts
├── tsconfig.json
├── tslint.json
└── serve.js

Proje düzeyinde genel görevleri gerçekleştirme

Oluşturulan proje aşağıdaki npm komut dosyalarını destekler:

cd project-directory/
npm run build

cd project-directory/
npm run lint
npm run compile
npm test

cd project-directory/
npm run start

IDENTIFY işleyicisini uygulama

Google Home veya Google Nest cihaz yeniden başlatıldığında ve doğrulanmamış yerel cihazlar (merkeze bağlı son cihazlar dahil) gösterildiğinde IDENTIFY işleyici tetiklenir. Yerel Ev platformu, daha önce belirttiğiniz tarama yapılandırma bilgilerini kullanarak yerel cihazları tarar ve IDENTIFY işleyicinizi tarama sonuçlarıyla arar.

Yerel Ev platformundaki IdentifyRequest bir LocalIdentifiedDevice örneğinin tarama verilerini içerir. Cihazı keşfeden tarama yapılandırmasına bağlı olarak, yalnızca bir device örneği doldurulur.

Tarama sonuçları cihazınızla eşleşiyorsa IDENTIFY işleyiciniz, akıllı ev meta verileri (türler, özellikler ve rapor durumu gibi) içeren bir device nesnesi içeren IdentifyResponsePayload nesnesi döndürmelidir.

Google, IDENTIFY yanıtındaki verificationId, SYNC yanıtının döndürdüğü otherDeviceIds değerlerinden biriyle eşleşirse bir cihaz ilişkilendirmesi oluşturur.

Örnek

Aşağıdaki snippet'lerde, bağımsız cihaz ve hub entegrasyonları için IDENTIFY işleyicilerini nasıl oluşturabileceğiniz gösterilmektedir.

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const verificationId = "local-device-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: device.id || "",
          verificationId, // Must match otherDeviceIds in SYNC response
        },
      },
    };
    return response;
  };

const identifyHandler = (request: IntentFlow.IdentifyRequest):
  IntentFlow.IdentifyResponse => {

    // Obtain scan data from protocol defined in your scan config
    const device = request.inputs[0].payload.device;
    if (device.udpScanData === undefined) {
      throw Error("Missing discovery response");
    }
    const scanData = device.udpScanData.data;

    // Decode scan data to obtain metadata about local device
    const proxyDeviceId = "local-hub-id";

    // Return a response
    const response: IntentFlow.IdentifyResponse = {
      intent: Intents.IDENTIFY,
      requestId: request.requestId,
      payload: {
        device: {
          id: proxyDeviceId,
          isProxy: true,     // Device can control other local devices
          isLocalOnly: true, // Device not present in `SYNC` response
        },
      },
    };
    return response;
  };

Hub'ın arkasındaki cihazları tanımlama

Google bir hub cihazını tanımlarsa çoğaltıcıyı hub'ın bağlı son cihazları için bir boru olarak değerlendirir ve bu son cihazları doğrulamayı dener.

Google'ın, bir hub cihazının mevcut olduğunu onaylamasını sağlamak için IDENTIFY işleyicinizle ilgili aşağıdaki talimatları uygulayın:

• SYNC yanıtınız kulübeye bağlı yerel bitiş cihazlarının kimliklerini bildirirse isProxy alanını trueIdentifyResponsePayload olarak ayarlayın.
• SYNC yanıtınız hub cihazınızı raporlamazsa IdentifyResponsePayload bölümünde isLocalOnly öğesini true olarak ayarlayın.
• device.id alanı, hub cihazının kendi yerel cihaz kimliğini içerir.

REACHABLE_DEVICES işleyicisini uygula (yalnızca Hub entegrasyonları)

REACHABLE_DEVICES amacı, hangi son cihazların yerel olarak kontrol edilebileceğini onaylamak için Google tarafından gönderilir. Bu amaç, Google'ın keşif taraması yaptığı her seferde (yaklaşık olarak dakikada bir kez) tetiklenir. Çünkü merkezde çevrimiçi olduğu algılanır.

REACHABLE_DEVICES işleyicisini IDENTIFY işleyicisine benzer bir şekilde uygularsınız. Ancak işleyicinizin, yerel proxy (yani hub) cihazı tarafından erişilebilen ek cihaz kimliklerini toplaması gerekir. device.verificationId alanı, hub'a bağlı bir son cihazın yerel cihaz kimliğini içerir.

Yerel Ev platformundan ReachableDevicesRequest, LocalIdentifiedDevice örneğini içerir. Bu örnek üzerinden proxy cihaz kimliğini ve tarama sonuçlarındaki verileri alabilirsiniz.

REACHABLE_DEVICES işleyiciniz, hub'ın kontrol ettiği son cihazları temsil eden verificationId değerlerinden oluşan bir devices nesnesi içeren ReachableDevicesPayload nesnesi döndürmelidir. verificationId değerleri, SYNC yanıtındaki otherDeviceIds ile eşleşmelidir.

Aşağıdaki snippet'te REACHABLE_DEVICES işleyicinizi nasıl oluşturabileceğiniz gösterilmektedir.

const reachableDevicesHandler = (request: IntentFlow.ReachableDevicesRequest):
  IntentFlow.ReachableDevicesResponse => {

    // Reference to the local proxy device
    const proxyDeviceId = request.inputs[0].payload.device.id;

    // Gather additional device ids reachable by local proxy device
    // ...

    const reachableDevices = [
      // Each verificationId must match one of the otherDeviceIds
      // in the SYNC response
      { verificationId: "local-device-id-1" },
      { verificationId: "local-device-id-2" },
    ];

    // Return a response
    const response: IntentFlow.ReachableDevicesResponse = {
      intent: Intents.REACHABLE_DEVICES,
      requestId: request.requestId,
      payload: {
        devices: reachableDevices,
      },
    };
    return response;
  };

EXECUTE işleyicisini uygulama

Uygulamadaki EXECUTE işleyiciniz, akıllı komutlarına mevcut bir protokol aracılığıyla erişmek için kullanıcı komutlarını işler ve Local Home SDK'sını kullanır.

Yerel Ana Sayfa platformu, bulut karşılama amacınız için EXECUTE işleyici işlevine aynı giriş yükünü geçirir. EXECUTE Benzer şekilde EXECUTE işleyiciniz çıkış amacını EXECUTE amacının işlenmesiyle aynı biçimde döndürür. Yanıt oluşturmayı kolaylaştırmak için Local Home SDK'nın sunduğu Execute.Response.Builder sınıfını kullanabilirsiniz.

Uygulamanızın, cihazın IP adresine doğrudan erişimi yok. Bunun yerine, şu protokollerden birini temel alan komutlar oluşturmak için CommandRequest arayüzünü kullanın: UDP, TCP veya HTTP. Ardından, komutları göndermek için deviceManager.send() işlevini çağırın.

Komutları cihazlara hedeflerken, cihazla iletişim kurmak için SYNC yanıtındaki cihaz kimliğini (ve varsa customData alanındaki parametreleri) kullanın.

Örnek

Aşağıdaki kod snippet'i, EXECUTE işleyicinizi nasıl oluşturabileceğinizi gösterir.

const executeHandler = (request: IntentFlow.ExecuteRequest):
  Promise<IntentFlow.ExecuteResponse> => {

    // Extract command(s) and device target(s) from request
    const command = request.inputs[0].payload.commands[0];
    const execution = command.execution[0];

    const response = new Execute.Response.Builder()
      .setRequestId(request.requestId);

    const result = command.devices.map((device) => {
      // Target id of the device provided in the SYNC response
      const deviceId = device.id;
      // Metadata for the device provided in the SYNC response
      // Use customData to provide additional required execution parameters
      const customData: any = device.customData;

      // Convert execution command into payload for local device
      let devicePayload: string;
      // ...

      // Construct a local device command over TCP
      const deviceCommand = new DataFlow.TcpRequestData();
      deviceCommand.requestId = request.requestId;
      deviceCommand.deviceId = deviceId;
      deviceCommand.data = devicePayload;
      deviceCommand.port = customData.port;
      deviceCommand.operation = Constants.TcpOperation.WRITE;

      // Send command to the local device
      return localHomeApp.getDeviceManager()
        .send(deviceCommand)
        .then((result) => {
          response.setSuccessState(result.deviceId, state);
        })
        .catch((err: IntentFlow.HandlerError) => {
          err.errorCode = err.errorCode || IntentFlow.ErrorCode.INVALID_REQUEST;
          response.setErrorState(device.id, err.errorCode);
        });
    });

    // Respond once all commands complete
    return Promise.all(result)
      .then(() => response.build());
  };

QUERY işleyicisini uygulama

Uygulamadaki QUERY işleyiciniz, kullanıcı isteklerini işler ve akıllı cihazlarınızın durumunu bildirmek için Yerel Ev SDK'sını kullanır.

Yerel Ev platformu, bulut istek karşılama amacınıza gelen QUERY işleyici ile aynı istek yükünü "QUERY" işleyici işlevine iletir. Benzer şekilde, QUERY işleyiciniz QUERY amacının işlenmesiyle aynı biçimde veriler döndürür.

Hub'ın arkasındaki cihazlara komut gönderme

Bir hub'ın arkasındaki son cihazları kontrol etmek için merkezin, komutun hangi cihazı hedeflediğini belirleyebilmesi amacıyla merkeze gönderilen protokole özel komut yükü hakkında ek bilgiler sağlamanız gerekebilir. Bazı durumlarda bu, doğrudan device.id değerinden çıkarılabilir. Ancak olmadığı durumlarda, bu ek verileri customData alanının bir parçası olarak eklemeniz gerekir.

Uygulamanızı TypeScript kullanarak oluşturduysanız uygulamanızı JavaScript'e derlemeyi unutmayın. Kodunuzu yazmak için istediğiniz modül sistemini kullanabilirsiniz. Hedefinizin Chrome tarayıcı tarafından desteklendiğinden emin olun.